Beginners Guide to Writing Documentation
Dev published on 2015-10-05T22:16:03Z

Original Post: http://write-the-docs.readthedocs.org/writing/beginners-guide-to-docs/

Source: https://github.com/writethedocs/docs/blob/master/docs/writing/beginners-guide-to-docs.rst

I find it best to start off with a selfish appeal. The best reason to write docs is because you will be using your code in 6 months. Code that you wrote 6 months ago is often indistinguishable from code that someone else has written. You will look upon a file with a fond sense of remembrance. Then a sneaking feeling of foreboding, knowing that someone less experienced, less wise, had written it.

As you go through this selfless act of untangling things that were obvious or clever months ago, you will start to empathize with your users. If only I had written down why I had done this. Life would be so much simpler. Documentation allows you to transfer the why behind code. Much in the same way code comments explain the why, and not the how, documentation serves the same purpose.

Author

Leading Community of Kids Coding, Making, Owning Education.

Join Community