Documentation and version control

Question

Given a project I'm about to start there will be documentation produced.

What is the best practice for this?

Should the documents live with the code and assets or should there be a separate documentation store?

Edit

I'd like a wiki but I will need to print the documents etc... It's a university project.

Answer 1

Here's a 2017 summary of the options and my experience:

(extreme 1) Completely external (e.g. a wiki, Google Docs, LaTeX, MS Word, MS Onedrive)

• People aren't bothered about keeping it up to date (half of them don't even know where to find the page that needs updating since it's so out of the trenches).
• wiki platforms are “captive user interfaces” - your data gets stored in their proprietary schemas and is not easy to examine with a simple text editor (Confluence is even worse in that you have no access to the plaintext content at all anymore)

(extreme 2) Completely internal (e.g. javadoc)

• pollutes the source code, and is usually too low level to be of any use. Well-written source code is still the best form of low level documentation.
  • However, I feel package-info.java files are underutilized.

(balance) Colocated documentation (e.g. README.md)

• A good half way solution, with the benefits of version control. If a single README.md file is not enough, consider a doc/ folder. The only drawback of this I've seen is whether to source control helpful graphics (e.g. png files) and risk bloating the repo.
  • One interesting way to avoid this problem is to use plaintext diagram tools (I find Grapheasy and Text Diagram to be a breath of fresh air).
• plaintext can be easily read even if your rendering engine changes as the years go by.

Github's success is in no small part thanks to its README.md located in the root of the project.

One tiny disadvantage of this approach though is that your continuous integration system will trigger a new build each time you make edits to the README.md file.

Answer 2

This is an interesting question -- basically, what others are saying is right about generated documentation, source files and templates/etc. should be stored in source control and generated during your build process.

As far as requirements/specs/etc. documentation, I have worked both ways, and I very much prefer using SharePoint or a Wiki/document portal that is designed for document sharing/versioning. The reason is, most non-developer folks aren't comfortable working with source control systems, and you don't gain any of the advantages of intelligent merging if you are using a binary format like Word. Plus it's nice to have internet-based access so you can reference and work on the docs in a distributed team without people having to install extra software.

Answer 3

Are you using any sort of auto-documentation or is it completely manual? Assuming that you are using an auto-documentation system, the documentation is more or less generated on the fly, and would be part of the code itself.

To me, (assuming that it's possible with whatever code you are using), this would be the preferred method of handling it, as you wouldn't need to maintain the documentation source at all.

Answer 4

I think most of us in the industry are not really following best-practices and it of course also depends a lot on your situation.

In an agile environment where you would have a very iterative process of release, you will want to "travel light". In this particular case, Jason's suggestion of a separate Wiki really works great.

In a water-fall/big bang model, you will have a better opportunity to have a decent documentation update with each new release. Also you will need to clearly document what version of the requirements was agreed on and have loads of documentation for every tiny change you do to requirements (due to the effects it has on subsequent stages). Often if the documentation can live together with the version controlled source code it is the best.

Answer 5

If you are writing versioned user documentation associated with each release of the product, then it makes sense to put the documentation in source control along with its associated product release.

If you are writing internal developer documentation, use automated internal source code documentation (javadoc, doxygen, .net annotations, etc) for source level documentation and a project wiki for design level documentation.

Answer 6

It really depends on your team. Where I work, we keep documentation in a wiki which is linked in with our team website. For the purposes of shipping documentation, the wiki can be exported and we run it through a parser that "fancifies" the look and feel of the documentation for customer purposes.

Storing the documentation with the code (typically in your source repository) is not a bad idea. Just make sure to keep them separated. For example, keep a docs folder which is on the same level with your src folder in your repository. This way, you can quickly ship the current documentation, you can easily track revisions, and anybody new to the project can immediately jump in without having to go to multiple locations for information.

Answer 7

Storing it in source control is fine.