Page cover

Confluence documentation

As the quote states, the importance of documentation is unprecedented. When working on problems and gaining new insights, write down the findings so later you don’t have to remember the ten steps you went through the first time but just to remember the one step Look up the Confluence Documentation!

Guidelines

When writing Confluence Documentation the agreed upon guidelines on the company level should serve as a compass:

#
Code
Description

1

DOC-001

All documentation shall be provided in English.

2

DOC-002

User guide for all features in all software components shall be provided.

3

DOC-003

Operation and maintenance guide shall contain following information:

  • Installation and upgrade instructions covering each step

  • Instructions how to run a specific software component comprising of but not limited to: startup, shutdown and monitoring of the system's health

  • Security procedures instructions providing necessary information for handling user credentials(Phase 2)

  • Error messages shall have unique error code and explanations of what is the meaning of an error, how to respond or correct the error and if possible information indicating the sub-system/module/package where the error occurred

  • Alarm Guides

4

DOC-004

System design document shall document the overall architecture design.

5

DOC-005

Release notes shall be provided prior to any delivery.

6

DOC-006

All software components are required to have detailed component design documents.

When to write it down

  1. Bug resolution: Provide detailed description of bug resolutions, including steps taken, encountered issues and solutions, along with relevant resource links.

  2. New functionality development: Document the functionality, including publicly available APIs and internal workings to facilitate user understanding and easier system integration.

  3. Technological exploration: Document insights and usage tutorials when incorporating new technologies or external libraries into the project.

Understanding the significance

To remember why documentation is so important, here are some points referenced from the Atlassian article (Importance of Documentation - The Workstream):

  1. A single source of truth saves time and energy - Documentation serves as a single source of truth, streamlining collaboration and decision-making processes.

  2. Documentation is essential to quality and process control - Documentation fosters consistency and adherence to established protocols, enhancing overall quality and process efficiency.

  3. Documentation cuts down duplicative work - By providing a reference point for past experiences and solutions, documentation minimizes duplicative efforts and accelerates problem resolution.

  4. It makes hiring and onboarding so much easier - Well-documented processes and procedures expedite the onboarding process, enabling smoother transitions and knowledge transfer among team members.

Last updated

Was this helpful?