Here is mine a IT-system documentation template. Once the documentation is in place it is widely used by developers, testers, users and management. Isn’t it much better to just refer to a paragraph in docs and send an URL to a colleague then describe the same thing over and over again in e-mails?

Who are the readers?

People who develop and support a IT-system. This covers a wide range of roles involved in software development live cycle: programmers, testers, designers, architectures, project managers, product owners and scrum masters, release managers etc. Especially important for newcomers!

When to start writing?

As early as possible once you have something stable that worth sharing with colleagues.
And it is never late to start writing. Some of my projects did not have any documentation at all, just email with passwords and IPs. Sounds familiar, right? Some others had just a couple of outdated doc files. Does not matter! If the IT system is alive documentation will be useful.

What to write first?

There is no particular order. Just keep the structure. Fill the paragraphs that are most important for the moment, document questions that are most requested in emails.

Who is responsible to start the process?

Project manager or scrum master are the right roles to start the documentation process in my opinion.
This responsibility includes:

• installation of the documentation engine
• creating the initial pages structure
• activating users

Who is responsible for updates?

Those who use the documentation is responsible for it’s update. This is basically everyone who is involved in software development.

When to update documentation?

I use two approaches to keep the documentation up-to-date:

1. Task based

Does your work split into tasks? If yes then every task should have time to document changes if needed. Complete a task, read related documentation and eventually update it. You can even have a separate stage in your workflow: documentation. And a task is not complete until the documentation is not updated.

2. Questions based

If a question was asked at least twice then the answer to it must be documented. Next you are asked about it again just refer to the documentation.

Where to write?

Here should requirements come. Functional, technical, security, business, price.
The very simple functional requirements to a document engine are:

• It must have search by words
• It must be web-based and available in any browser
• It must have code highlighting
• It must support auto generation of table contents

It is definitely not SharePoint, EPiserver, WordPress or any other CMS monster.
Here are my choices:

• Wiki. Here is a list of wiki engines. Global wikipedia.org uses MediaWiki
• Atlassian Confluence

Documentation structure

IT-system documentation should contain at least three parts:

• Functional – it covers functionality of the system
• Technical – describes how the system is build. What technologies are used
• Operational – describes how to operate the system, support it

Template

And finally the template.

1. About

Short explanation what is it all about.

2. Functional

Who are the users
API description
Links to users documentation if external
Links to lows and regulations

3. Contact list

List should include names, roles, emails, phone numbers, company.

3.1 Current development team

3.2 Management team

3.3 Retired team members, companies, old system owners

Whoever had the responsibility for the system in the past

4. Operational

4.1 Remote access

How to access servers. VPN etc.

4.2 Network infrastructure

Include high level design drawing and low level design drawing.

4.3 Server infrastructure

Include high level design drawing and low level design drawing.
List of all servers with roles, IP addresses, DNS names, logins, configurations etc.

4.4 Configuration

Include all important configuration files.

4.5 Logging

Where are logs. How to get access to logs. How to search logs.

4.6 Backup

How to backup. How to restore backup. How often backup is done. Who is responsible for backup.

4.7 Licenses

It is nice to have a table with component name, price, license key (or where to find it), price, expiration date.

4.8 Source control

Where the source is placed. How to get access to it.

5. Technical

5.1 Technology

General description of technology. ASP.NET Core, Angular, node.js etc

5.1.1 Libraries and components

List over libraries and components and tools that were used to create the system.

5.2 Persistence layer. Database

Describe the concept.
What tables are most important.
How to search important data. Some useful SQL examples.

5.3 Components

If the system is distributed list the components here.

5.4 Interrogation points

If the system speaks to other systems give a list over integration points.

5.5 Access control

Describe AAA autehntication, authorization and accounting here.

5.6 Build process

How to compile and build system from source code.

5.7 Deployment

How to deploy the system. Every component of it. From command line from a workstation, from continues integration server.

5.8 External documentation

Links to any useful external technical documents.

6. Test documentation

Test users and roles.
Test plans.
Test tools.