I think this article offers some very good advice about the need for different types of documentation to support software. I am far more likely to try a new piece of software if it comes with clearly signposted online documentation covering how to install/use the 'ware, and why to use it, in addition to a well presented technical reference.
In my view, getting the documentation balance right is critical - having too much documentation (I'm staring at Google and AWS here) can be almost as bad as having too little of it. Making the documentation easy to navigate is as important, for me, as making sure the information supplied is accurate and up to date.
My personal experience - principally from attempting to document my Javascript library[1-6] - is that generating the documentation is just the start of the process. Keeping that documentation accurate and up-to-date as I developed the library across minor and major versions soon became a massive burden which eventually led me to put further development on hold; the latest work I have done on the library remains in a branch on GitHub while I think of better ways of developing and presenting the necessary documentation around it.
[1-6] - My different attempts to document my Javascript library, as a demonstration of how messy the whole process can get:
[1] - http://scrawl.rikweb.org.uk/ - the Tour page, with "marketing copy" which attempts to sell the library to potential users.
[2] - http://scrawl.rikweb.org.uk/tutorial.html#HTML5_page - the "Simple Docs" page is an excellent example of confused documentation as it tries to combine tutorial, how-to and explanation in the same document.
[3] - http://scrawl.rikweb.org.uk/demos.html - I added the "Demos" page to support the "Simple Docs" page; in fact the demos were (are) the visual testing regime I developed for the code base.
[4] - http://scrawl.rikweb.org.uk/docs/ - the "Technical" documentation - generated from inline comments in the source code. I chose the wrong tool to do this, as it expects the code base to be object-oriented; the library's Javascript (v6) is procedural/prototypal, and decidedly not modular.
[5] - http://rikweb.org.uk/wp/ - at one point I decided that a good way to supply "how-to" information was through blog posts. This was one of my less clever decisions and quickly abandoned.
[6] - http://scrawl.rikweb.org.uk/learn.html#lesson001 - my best attempt at supplying potential users with tutorial documentation. Embedded Codepens make the experience a bit more interactive, but the results are probably too primary school given that my target audience for the library was more experienced front-end developers.
In my view, getting the documentation balance right is critical - having too much documentation (I'm staring at Google and AWS here) can be almost as bad as having too little of it. Making the documentation easy to navigate is as important, for me, as making sure the information supplied is accurate and up to date.
My personal experience - principally from attempting to document my Javascript library[1-6] - is that generating the documentation is just the start of the process. Keeping that documentation accurate and up-to-date as I developed the library across minor and major versions soon became a massive burden which eventually led me to put further development on hold; the latest work I have done on the library remains in a branch on GitHub while I think of better ways of developing and presenting the necessary documentation around it.
[1-6] - My different attempts to document my Javascript library, as a demonstration of how messy the whole process can get:
[1] - http://scrawl.rikweb.org.uk/ - the Tour page, with "marketing copy" which attempts to sell the library to potential users.
[2] - http://scrawl.rikweb.org.uk/tutorial.html#HTML5_page - the "Simple Docs" page is an excellent example of confused documentation as it tries to combine tutorial, how-to and explanation in the same document.
[3] - http://scrawl.rikweb.org.uk/demos.html - I added the "Demos" page to support the "Simple Docs" page; in fact the demos were (are) the visual testing regime I developed for the code base.
[4] - http://scrawl.rikweb.org.uk/docs/ - the "Technical" documentation - generated from inline comments in the source code. I chose the wrong tool to do this, as it expects the code base to be object-oriented; the library's Javascript (v6) is procedural/prototypal, and decidedly not modular.
[5] - http://rikweb.org.uk/wp/ - at one point I decided that a good way to supply "how-to" information was through blog posts. This was one of my less clever decisions and quickly abandoned.
[6] - http://scrawl.rikweb.org.uk/learn.html#lesson001 - my best attempt at supplying potential users with tutorial documentation. Embedded Codepens make the experience a bit more interactive, but the results are probably too primary school given that my target audience for the library was more experienced front-end developers.