Why Write Documentation
I like writing documentation because I would learn something new and I would share it with developers as many as I can.
I may be stating the obvious here. We write documentation because:
To understand better
By writing processes in your own words, you can understand the process better. How and why the products works that way.
To help us remember stuff
I'm sure when developers move from one project to the next before going back to the starting project, they are going to forget how/why a project works that way. This happened to me a couple of times.
We need documentation to remind ourselves the purpose behind a process or a product.
To help your colleagues
You might help your colleagues to learn something new or to help identify issues.
The following examples might happen. Your fellow developers who are learning the ropes on a legacy project, they might benefit from instructions. Helpdesk colleagues can pick up tips from troubleshooting sections.
Shared Knowledge
One of the top reasons in writing documentation is you need to share your knowledge with colleagues, in the event you move on from your role.
Otherwise, that knowledge is lost and your colleagues are working in the dark to resolve an issue. In the past, when a developer has left, other developers struggled to understand why/how a particular process worked.
It helps colleagues to fill in gaps in their knowledge.
How to Write Documentation
Those are tips. You don't have to accept all of them. Feel free to take some of them and mix them up to your preference.
Use a Wiki
Write up your documentation on a wiki. Don't use Word. Files gets easily lost. You can export from a wiki to a file.
You would like to able to direct your colleagues to an URL on a particular subject. They can dig deep into the wiki for further reading.
Wiki pages can be kept up to date and colleagues can return to the same page via their bookmarks.
I've used MediaWiki and Conflucence Wiki. Those wikis are handy.
Be consistent
Be consistent in your writing. Don't interchange words when they mean the same thing. For example, interchanging process with function when they refer to the same thing.
Don't write a wall of text
Don't write a wall of text. Your colleagues will have difficulty reading it. I see a wall of text as someone talking at length without pausing for breath.
Break it up into paragraphs or sections.
Add Website links
Add Website links to help your colleagues to do some further reading.
If you're writing instructions on how to use SFTP with a client's server and credentials are a different page, create a link to that page. Don't copy and paste the credentials on the wiki page as credentials are subject to change.
If they do get chnaged, it will be updated on that page. You don't need to worry about it.
Add Screenshots
Where possible, add screenshots to accompany your documentation. You might be writing a series to steps to reproduce an issue.
Your colleagues may wish to make sure they're following it right. Add screenshots to guide them. They'll thank you for it!
Use Headers
Add headers to your documentation e.g h1, h2, h3. They'll help your colleague to identify key areas they may be interested in. They'll help break up your text, also.
If you're using a wiki to document your project, headers can also be used as links in a table of contents. When someone go to the top of your wiki page, they can click on the link to scroll directly to the section on the sdame page.
Headers are also beneficial when you export it to a Word or a PDF file. In some wikis, it creates a set of links at top of the exported document.
Summary
Documentation helps you and everyone else to understand the purpose of a project and become quickly up to date.
Oldest comments (2)
Documentation is one of those things that seems obvious until it comes time to actually do it, then everyone groans. My personal approach is to document as I code. Breaking it up into small chunks like this not only reduces the psychological burden, but it also means that you're documenting what you're doing as you're doing it, so it's fresher in your mind! A win-win!
That's right. Documenting and the way we document are important.
Also worth noting that documentation isn't limited to text but graphics, charts, tables, flows, etc.
There are many ways to document and not die while doing it xD
I wrote a blog post for the company I work regarding the topic.