How to keep documentation up to date and accessible [duplicate]

Question

The problem: Documentation is in code in the form of docs, its in wiki websites, its written down on notes, in diagrams and issue management systems.

When documentation is so spread out, how does one manage to keep it up to date and relevant?

Answer 1

What you need to do is develop a single source of information.

Depending on the tools and processes that you use, you probably don't need it in all of those places. I'm not sure what your requirements for documentation are, but that will likely drive what tool you use as the single point of reference. Minimally, you should start collating everything electronically and make it generally available to the team - get it out of physical paper and into electronic sources that are searchable, indexed, and backed up.

From there, decide on the best methods of capturing information for your needs.

Answer 2

Make updating the various documents part of your "definition of done".

Assuming you are using agile methods, your work will be broken down into tasks. Any change to the primary documentation (the code) will likely trigger the need for changes to supplementary docs (tests, wiki entries, comments, diagrams, word docs etc). So as part of the task, the assigned person should update affected docs and those docs should be checked as part of the reviews of the changes made by that task. Only once everything (not just the code) is updated, checked-in, reviewed and tested, should the task be considered complete.

Answer 3

Alas, few organizations actually succeed at curating and then keeping documentation both accessible and up-to-date.

I am a contract engineer who has worked for more than 120 distinct companies, some of which you know of.

Large (50,000+ employee) companies might have effectively no standards or systems for documentation. Or they have an onerous, one-size-fits-all system. Neither works very well in practice. The former because it just doesn't get done. The latter because the difficulty of providing useful writing is high and updating it is even more painful.

Small companies (less than 50 employees), on average, do a much better job of requesting and maintaining internal and external documentation for computer software. I note that the best documentation is the internal flavor written by the engineer and inserted into the source code at the time the code is written. Automatic extraction tools nicely encourage this practice being followed.

One- or two-person projects also usually do quite a good job of keeping documentation together with the source code and keeping it relevant.

Open source software perhaps have the best functional examples. Look at the Linux kernel: The architectural and how-to information is part of the git repository and appears in the Documentation/ subfolder at the root of the project.

Answer 4

@ThomasOwens mentioned the most important part, Single Source

So you should start,

• Adding all new docs to a single source,
• When making schedules, add move current documentation to new source bullet to todo list. Spending a separate time to move all documents from all around to a single source is hard, but people may update docs when then maintain related service, update the related code base, need the document but have hard time finding or another employee may had hard time finding docs. Doing the move and merge thing when you are dealing with the related doc or service is easier.

You can also have a distributed source system which is managed from a single place!

• You can have a document server, place all docs there. Any you can have a script which runs every midnight and inspect files, creating wiki directories and wiki headlines according to folder/file structure and update the wiki pages according to related files using file names.
• You can have a web-based documentation tool where you prepare and update documents on a software and the software can create/update docs (on hard drives) on local or remote machines, update wiki pages etc.

If you managed to keep all of your docs in the same place, then you can distribute read-only copies to anywhere you want.