Why good documentation can get you more love than $1000

Anytime I am asked to find and incorporate some 3rd party for a feature (e.g. A mass texting service so we can text our members), the first thing I find out about each potential candidate is "does their API have good documentation?" This is because bad documentation can be an absolute nightmare. In some cases, it is easier to create the feature from scratch, than to try and figure out the documentation.

You can spend well over $1000 dollars on the right hardware & software configuration to help you do the best at your job, but if you never put in the extra effort, you will never be the best.

We all get it, writing documentation usually sucks... a lot. But in the end, it is worth it., because while it may not make you developer of the year, good documentation can make you a real hero.

Some things that can improve your documentation

• Be detailed but to the point. Most people just want to know what it does, not it's life story from conception.
• Point to important files [downloadable scripts]. If a script largely depends on a particular file, or set of files, it may be a good idea to mention that file in your documentation.
• Organization is key. Separating thing out into sections can make information easier to absorb. Additionally this can make it easier to search for stuff.
• Use simple explanations. When trying to explain anything, pretend that this is only the second page in the documentation that the reader has read. Treat them as if they know a little, but not everything.
• Use direct examples. Examples are an important part of any documentation, they allow the reader to get an in-depth feel for how things should be done. When writing examples, try and minimize excess script. To much script can sometimes be confusing.

Thanks for reading

If you enjoyed what I wrote, consider upvoting this protip or endorsing me.
If you want to see more of my stuff, you can see other protips I have written or visit my profile.