Either commit to keeping documentation rigorously up to date, or save yourself the effort to write it. With code it's easy: keep the documentation in the same repository as your code and make documentation an integral part of the review process.
-
I believe that having atomic commits that bind together production code, testing code and documentation (along with other necessary artifacts—e.g. deployment scripts) is the only way to keep documentation up to date. If the docs are outdated, they'll cause a bad user experience.
I think it would be nice, but too difficult to achieve. If a method is discovered to be buggy after release, there's no way to tell users that in the version of the documentation that's in that release. Documentation needs to evolve to be kept up-to-date...
-
-
But with that approach the only right thing to do is to delay documentation until the software is dead stable, unmaintained, unsupported. You raise an important point, but I believe this is a concern orthogonal with respects to documentation (continues).
-
No, I don't think there's that constraint: I propose coding and documenting in parallel, and independently. Release the code when it's ready, and keep releasing the docs continuously for all versions you care about. Tools should help with this, though.
End of conversation
New conversation -
-
-
Here by "documentation" I refer to a natural language in-depth description of the software and the necessary steps needed to use it. I would leave bug awareness to other tools, like issue trackers and changelogs (among others).
-
I like that too, but it's somewhere different to look. Right now we don't even have the option of documenting bugs if we wanted to...
End of conversation
New conversation -
-
-
Final point: if by policy you delay docs release, how are your users incentivized to keep up to date about your project (including it's bugs) with those.
-
It wouldn't be the policy to delay, so much as to avoid putting the pressure on having perfect docs at the point of release. It's trying to reduce the friction in writing documentation at any time.
- Show replies
New conversation -
-
-
(missing question mark at the end of the previous tweet, sorry)
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
Loading seems to be taking a while.
Twitter may be over capacity or experiencing a momentary hiccup. Try again or visit Twitter Status for more information.