I view a video about the documentation. It was a conference given at a YUI Conf. The topic was documentation for software, especially when you don’t have anyone dedicated to the task. I am dedicated to the documentation process and content at eZ Systems since 3 months.
What did I wrote down my paper (yes, I am old fashioned sometimes) viewing this video ? (It will be the content of the conference filtered by my brain).
« To first order software documentation is like code ».
It means that Documentation is part of your project, and doc lives in your repository.
I really am convinced by this approach, the documentation for tech stuf has to be near the code.
Code is in the repository because :
- powerful version control
Documentation elsewhere is duplicating the powerful repository. Documentation is plain text.
Code is expensive (and doc is worse) : this will lead to consequences for someone. If you have choice between fix your code and writing doc : fix your code.
Developer Setup Page Wiki : NO ! MORE !
Use instead :
- automtation build
Offline editing is the best, because it’s freedom.
Dont allow user comments on doc pages :
- they give bad advices (php.net, AngularJS)
- adding pixels to the doc out of your control is a bad idea
Add pixels/increase your doc size with value.
Replace comments by a link to forums on the topic (reactJS)
Topic of documentation
What ? How ? = code
Why ? = documentation
Code extract in doc
- line numbers
DRY doc = cross references with links, not duplicate content
Build targets : HTML, ePub, PDF, TROFF
Questions from the audience :
?/ About the user comments
More pixels in the doc = be careful
=> lot of feedback (is it the place ?)
=> not useful (as doc)
=> moderation to make
?/ What about XML ?
Docbook XML was ok before we have the lightweight markup format (Markdown, ie)
?/ What if we have a documentation debt ?
Write documentation as you go, just like covering with unit testing a legacy code