Having been a long term Perl developer I have used, read, liked, written and learned from a lot of technical documentation as the one found on CPAN. Back in 2011 Chromatic wrote a good piece entitled: “Victims of the Success of CPAN Documentation”, this piece hit the nail on the head and addresses one of my long time concerns and issues with technical documentation.

“It is not always user-friendly”

I have played around with the idea of extending my documentation boilerplate/template with a section named: “Features”. The idea of the “Features” section would simply be to add information on some basic use-cases, recommended uses and core functionality (what does it do).

Often technical documentation only lay out the bricks and building blocks, letting it be up to the user to assemble the pieces, much like Ikea furniture. Ikea furniture however does have one clear advantage over software components, it does have a clearly stated goal: “You can eat|sit|sleep|contain|relax with X”, meaning Ikea sells an idea to the end-user before the fact of assembly-process comes to mind of the customer.

Software components are not Ikea furniture, it is more like LEGO bricks. but also LEGO sells the idea of a working concept, instead of just a box of bricks – you get the bricks, but you also get the blueprint. Yes you can build constructions of your own design and yes you can combine with other LEGO sets.

My youngest son builds a lot of LEGO, yes he can follow the assembly guide, and yes he an build stuff of his own design, but in a place where he truly excels is in the remix of LEGO sets. He loves taking apart standard models or models I have built, but instead of breaking them into atoms, he breaks them down to smaller LEGO models and then he combines them to alternative models – a lot of this is retrofitting guns and cannons, but that is not important for this blog post.

So when we want somebody to use our open source software, we need to sell the concept. Yes there are plenty of ways to “sell” the software, demo videos, blog posts etc. – but users think in use-cases and with the amount of open source software available, it can be hard to decide on which solution to pick – you evaluate on a lot of different parameters (this could be a blog post by itself), and one of them is sometimes documentation.

So documentation should be considered a factor to make somebody choose your software instead of some other implementation. This means you have to describe some key parameters in order to sell the concept.

  • What does it do
  • If you use it like this, it is: fast/reliable/intuitive/interactive/customisable/beautiful
  • And in addition you can: produce/calculate/render/secure/build/execute/integrate

Describe features and key concepts and core functionality as an elevator pitch and you might hook the reader.

I have grown very fond of a plugin for Sublime Text, it is a pretty basic plugin, which creates a Table of Contents on a Markdown document.

I use it all of the time.

I looked at the documentation and I got it to work, as I said it is pretty basic and the documentation was sufficient, but not impressive. I sent a pull-request for a bug fix and I sent a pull-request for some documentation spelling corrections – all was accepted.

The author is really a cool guy and I love his software product. So I thought to myself. I am not a Python programmer (my first PR was the deletion of a line), perhaps I can contribute in another way – this piece of software is really marvellous and I want everybody else to see it, try it, use it and love it – just like me.

So I wrote him and asked – What do you think about a complete rewrite of the documentation?

And he said go ahead

So today I have sent him a pull-request with a complete re-write of the documentation going from a format focused on parameters in the software to a feature centered approach.

All of the pieces where there, all the examples, all the data – I simply shuffled it around and added some prose and rephrasing to make it more human-readable.

I do not know if my theory on this holds water, but I actually like the outcome of my work and I hope this new format will be more appealing to the potential users and existing users, who read the documentation to become wiser, or get the information on how to tweak the use of the software to their needs, because the software actually had a lot to offer, but it was not immediately clear, when skimming the documentation.

I know this might not apply to all types of documentation and yet again it might.

Give it a shot.