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 would actually suggest the opposite: keep documentation in a different repository so that it's easier to update at any time. Documentation almost always follows code, so when it's in the same repo, it's difficult to hold up a release because the docs aren't ready.
-
-
In a separate repo, the code can be released early, and PRs to the docs repo can be merged much more eagerly/optimistically at any time. You can also retroactively document bugs discovered in the code if they're not tied together.
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
-
-
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...
- Show replies
New conversation -
-
-
I find that documentation is just as important as code. Delaying it's development makes catching up harder and harder. I wouldn't delay tests and prefer to behave in the same way for docs.
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.