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

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.