Many years ago I made the mistake of documenting my Javascript library thing by building static web pages to explain it all. They became a nightmare to maintain, and made me scared to update anything in my library thing because it meant having to fix the web pages too.
A while later, during a significant recode exercise, I tried a different solution. Inline code documentation with YUIDoc - which was much better. Except YUIDoc assumes people are writing their Javascript in an Object Oriented way. My library thing didn't have a single class in it. The generated documentation just didn't make sense ... but by the time I realised this I had almost completed the documentation exercise and wasn't going to waste the work. So I also updated the static web pages too (finally!) and presented both sets of documentation on the Javascript library thing's website.
The thought of having to document changes and updates in two sets of documentation stopped me working on my Javascript library thing for over TWO years.
Last year, when I made the decision to rewrite my Javascript library thing from scratch, I also made the decision to dump all the documentation. Instead I wrote it as inline comments in simple Markdown - the most basic flavour available - and used a tool to auto-generate documentation from that (I've ended up using docco - it does the job).
Dumping all the documentation baggage has made me massively happier, and given me renewed love for working on my Javascript library thing.
... As for project runbooks? I write them in Google docs. If a client ever demands to see their project's runbook (please God no!), I can create a PDF of the latest version and email it to them.
A while later, during a significant recode exercise, I tried a different solution. Inline code documentation with YUIDoc - which was much better. Except YUIDoc assumes people are writing their Javascript in an Object Oriented way. My library thing didn't have a single class in it. The generated documentation just didn't make sense ... but by the time I realised this I had almost completed the documentation exercise and wasn't going to waste the work. So I also updated the static web pages too (finally!) and presented both sets of documentation on the Javascript library thing's website.
The thought of having to document changes and updates in two sets of documentation stopped me working on my Javascript library thing for over TWO years.
Last year, when I made the decision to rewrite my Javascript library thing from scratch, I also made the decision to dump all the documentation. Instead I wrote it as inline comments in simple Markdown - the most basic flavour available - and used a tool to auto-generate documentation from that (I've ended up using docco - it does the job).
Dumping all the documentation baggage has made me massively happier, and given me renewed love for working on my Javascript library thing.
... As for project runbooks? I write them in Google docs. If a client ever demands to see their project's runbook (please God no!), I can create a PDF of the latest version and email it to them.