I was a manager of developers in an organisation for a few years, and during that period I learned a lot. But if I’m honest, I learned far more about being a manager from leading a large open source projectfor 10 years, because that taught me a lot about what makes developers tick. Of course, I’ve always been a developer myself too, but you often don’t think that clearly about your own motivations.
Well, yes - and my apologies if you’ve already seen these. In celebration of the new blog and before I’ve polished any new entries for it - I often write & refine my posts over several sessions, I find the content is better that way - I thought I’d flag up three posts from this blog that I’m particularly satisfied with, and that I think resonated well with people. Work 2.
For 18 months I’ve been told by a succession of doctors and physios that I didn’t have anything structurally wrong with my spine and that my bouts of back pain were simply ‘standard non-specific back pain’ - ie muscle problems that I should just take NSAIDs for and exercise more. I’d been a bit skeptical because the problems were occasionally quite extreme and seemed to be always centred on one particular location (the joint just at the bottom of my ribcage), but after getting many opinions and one set of x-rays I went along with it.
Building a new technical documentation tool chain
Writing good documentation is hard. While I happen to think that API references generated from source code can be extremely useful, they’re only part of the story, and eventually everyone needs to write something more substantial for their software. You can get away with writing HTML directly, and separately using a word processor to write PDFs for so long, but eventually you need a proper tool chain with the following characteristics:
- Lets the author concentrate on content rather than style
- Generates multiple formats from one source (HTML, PDF, man pages, HTML Help etc)
- Does all the tedious work for you such as TOCs, cross-references, source code highlighting, footnotes
- Is friendly to source control systems & diffs in general
- Standard enough that you could submit the content to a publisher if you wanted to
- Preferably cross-platform, standards-based and not oriented to any particular language or technology
When I came to write the OGRE manual many, many years ago, I went with Texinfo - it seemed a good idea at the time, and ticked most of the boxes above. The syntax is often a bit esoteric, and the tools used to generate output frequently a bit flaky (texi2html has caused me many headaches over the years thanks to poorly documented breaking changes), but it worked most of the time.
I’ve been meaning to replace this tool chain with something else for new projects for a while, and DocBook sprung to mind since it’s the ‘new standard’ for technical documentation. It’s quite popular with open source projects now and it’s the preferred format for many publishers such as O’Reilly. In the short term, I want to write some developer instructions for OGRE for our future Mercurial setup, but in the long term, I’d really like a good documentation tool chain for all sorts of other purposes, and Texinfo feels increasingly unsatisfactory these days.
Having spent some time this week establishing a new working tool chain, and encountering & resolving a number of issues along the way, I thought I’d share my setup with you.
I’m not blogging as often these days; as you know I don’t traditionally ‘do’ short blog posts - in my book if something is worth blogging about, it’s worth making sure it holds together as an argument, and as a piece of writing generally - and a combined lack of time of anything I’m motivated (or permitted) to talk about has left the site a little bereft of content. Luckily my OGRE Twitteris stocked with more frequent and less lovingly crafted status updates on what I’m doing there.
Making a living from open source is hard. Correction - making a living from writing open source software is hard - it’s incredibly easy to make a living from someone else’s open source software of course, which is why that’s what most people do 😀At one time the popular opinion was that pure-play open source companies could make a living from support services, which works to a degree but I know from both my own experience and from that of others that it doesn’t work that well.
Gartnerhaven’t exactly been the sharpest tools in the box when it comes to predicting open source trends over the last few years, vastly underestimating it until about 2008, by which time it didn’t exactly take a professional analyst to tell you that it was popular. Still, now they’ve woken up to its potential, occasionally they post something useful. In particular, I liked a recent blog post about how open source is “trending towards customer obscurity”- that is to say that while open source is incredibly important to producers of software, the vast majority of consumers don’t really care how their software is made any more than they care how their car was made.
I picked this storyup via Matt Asayand it pretty much summed up the frustrations I’ve had in the last 10 years when talking to certain people about open source - particularly when I was involved in business software. Peter Gyorgy, CIO of GE made this comment in a recent panel discussion: “I think open source is great for own internal playground type of things but if it’s running vital mission critical applications - networks running on open source for example - then that is a huge, huge risk to the organisation,”
I always find Matt Asay’s blogan interesting read - even if I don’t always agree with him, his posts on open source are always thought provoking. Today he was talking about how Wikipedia’s contribution rate is falling and how that has parallels in open source; that the community is no replacement for a centralised, focussed team. He’s right on the core point - at the heart of every successful open source project there’s always a core team (or individual), and in the really influential ones, that team is usually funded - Mozilla is famously bankrolled almost entirely by Google, the Apache foundation has many, many sponsors including Google, Yahoo and Microsoft, Eclipse has IBM, and so on.
What a difference a few years can make. For a long time, Microsoft was seen as public enemy #1 of those who liked to promote, produce and consume open source (I’m deliberately not describing it as a ‘movement’ here - that implies political motivations which I assert that only a vocal minority have). It was entirely their own fault of couse; blustery, really quite bizarre tirades from the only two CEOs their company has ever had cemented their position as the McCarthy’s of the modern era.