So often doing something is simply not enough. You need to show what has been achieved, talk about it, point out how other people can use it, build upon it. Most importantly of all, though: write about it.

Words on paper cement your actions and efforts for everyone to admire. This is more true in the digital world than ; describing your code is arguably more important than writing code in the first place. After all, if it weren’t useful, why should anyone use it? Why would anything be done if it didn’t have end results? It may seem drudgery to spend a while writing up what you have spent the past while looking at, but it really does take a very short time when compared to the length of the contribution. Quite how so many developers labour over their projects for days to years, with the only hint on how it works shrouded in the programming syntax of the source code. This is nothing short of perplexing! Even for those that do not fit the stereotypical quiet, modest worker, proverbially blowing one’s own trumpet should be done on every worthy occasion!

• Found a niche or don’t like how other software solves a problem? Say so!

• Come up with a neat trick in your code? Borrowed some methodology from elsewhere? Brag about it in a blog post! Scribble a note in the “how awesome is my software?” section of the documentation.

Wait, you haven’t written any documentation? Get to it! No-one will know how important your work is unless you tell someone something about it!

Let’s take a moment to think about the broader picture. When you contribute something to a project, big or small, who will be affected by it?

• You.

This may be obvious but it goes deeper than one may expect: it doesn’t matter if you haven’t spent countless hours on a major project or merely minutes writing a small but useful patch (heck, they’re all useful if they’re good and even the bad ones are a start), you have spent time contributing to something. That’s time that could have been spent elsewhere. If it was coding, you will no doubt receive some kind of reciprocation for your efforts, be it a user thanking you or a member of the development team saying that it’s not how things are usually done and explaining how it should be. Your name will be noticed (believe me, it will) and it’s something you can use when trying to introduce yourself to other projects.

• Developers / Artists / Musicians / Writers…

For other members of the project, it’s work they won’t have to do! Their project will be improved and it will be directly because of you. Whether it be code, a new icon, a sound-bite or additions/corrections to a website, the quality will be raised.

• The World

What? I’m serious: your contribution may make your project that little bit better but that in turn raises the average. The little part of the world where your project sits has just become all the more special. The open-source movement has taken some flak for being weak in certain areas, a statement with which I agree, but conversely that means there are areas in which it succeeds. Its strengths would not be this great if people had not done something to make it so. Raise both the quality of your project and the bar for everyone else.

• Users

This is both the biggest and smallest point. There will no doubt be a great percentage of users that will never be known. They stumble across the project, decide to try it out from its blurb or feature list. They may use it regularly or keep it somewhere in their system for that one ‘just the job’ moment. There are others however, that get in touch — notes are left on the project or developers blog, posts are sent to a mailing list, comments added to a bugtracker. But how did these users become so in the first place? I’ll gave you a hint: they found your project because they wanted it to do something, because it does something they want, because someone has said it does.

Gotcha!

Someone has said it does. Someone has written something, somewhere, to say what the project is and perhaps its features. Hopefully, there will be some kind of specification for its use too, its requirements or prerequisites. These are perhaps the second pieces of information that comes out of a project, as most places that house projects would require some.

For some though, this is how far the documentation goes. If this is the case, it’s not finished. In other areas of production, this level of information isn’t just a bad idea, it’s illegal. Buy a pizza from a supermarket and it may have a delicious name and describe what a ‘deluxe’ topping actually is but it is a legal requirement to give other information. Okay, in software there is no such definition to documentation but it is highly expected when delivering high-quality products.

Some potential users, though, only use software that is made in a certain way, uses certain other software or won’t do certain things. How can they decide and then become actual users?

I’m not just talking about the ‘stage one’ documentation, though. While step-by-step installations instructions and a good README are essential to get up and running, truly useful documentation takes much more. Great examples are real-world tutorials, answers to frequently asked questions and a plain English explanation of features, not a technical list of all the ins-and-outs of the interface (while that has it’s place). Expect your users to want to understand your project rather than just click, “Go.”

While the argument that a good user interface should be easy enough to understand in order to use the project, it just isn’t enough. Why does that button perform that event? Where does this list of data come from? How can we change it and why should we want to? While there is no common line to adjudicate for how detailed your docs should be, all of them should be practical, useful words on getting the best out of your project. It may take time, but so too does writing the code and everyone will appreciate it tenfold should there be notes explaining what it does and how to use it in the broader sense.

How much documentation do you write? Do you only use software or real-world artefacts that come with decent instructions, an FAQ and a help or support mechanism? Do you think that if someone can’t figure out how to use something, they shouldn’t? What are the best examples of documentation that you have seen? Let’s make everyone’s efforts shine all the more!

(Big thanks to Carla Schroder’s blog post on Linux Today for inspiring me to write this!)