Skip to main content

Documentation Guidelines

Our wiki is based on the Open Source application called BookStack. Check the 📋 fundamentals and 📚 official documentation.

Why Do We Need Documentation?

Reason Description

Knowledge Management

 Documentation serves as a way to capture and preserve important information and knowledge within an organization. It helps ensure that critical information is not lost due to employee turnover or changes in leadership. 

Training & Onboarding

 Documentation can be used as a tool to train and onboard new employees. It provides a clear and concise source of information that helps new employees understand the company's policies, procedures, and processes.

Communication

 Documentation can serve as a communication tool, ensuring that all team members are on the same page and understand what is expected of them. It can also help facilitate collaboration and knowledge sharing between team members.

Continuous Improvement

 Documentation can help identify areas for improvement within a company's processes, policies, and procedures. It provides a record of past practices and helps identify opportunities for optimization and innovation.

Risk Management

 Documentation helps manage risks associated with the company's operations. It provides evidence of past decisions and actions, which can be used to evaluate the effectiveness of risk management strategies.

What Makes A Good Documentation?

By applying these principles, you will create useful and enjoyable documentation. Please, keep these in mind at all times while you are writing a page.

Principles Description

Clear and Concise

 The documentation should be written in a clear and concise manner, using simple language that is easy to understand. The use of jargon and technical terms should be kept to a minimum and explained when necessary.

Well-Organized

 The documentation should be well-organized and presented in a logical sequence. It should have headings, subheadings, and an index to help the reader quickly find the information they need.

Accurate

 The documentation should be accurate and up-to-date, reflecting the current state of things

Comprehensive

 The documentation should cover all the important aspects of the system or product being documented, including features, functionalities, and limitations.

User-Centric

 The documentation should be written with the end-user in mind, providing information that is relevant to their needs and expectations.

Visual Aids

 The documentation should include relevant images, diagrams, and videos to help explain complex concepts and processes.

Consistency

 The documentation should maintain consistency in its style and formatting, using the same terminology and language throughout.

Easy to Update

 The documentation should be easy to update, so that it can be kept current things evolve.

Always use BookStack's Headings to structure the content of your pages. This automatically generates the table of content of your pages in the left pane.

Content Organization

The PARA Method

The content of our wiki is organized following the PARA Method. It is based on 4 simple categories of content:

Category Description
Projects / Products

Definition: Time-bound efforts that we are working on now. 

 

Akvo: This is where we centralize the documentation about our current active projects and products.
Areas

Definition: Long term knowledge areas that we want proactively manage.

 

Akvo: This is where we document our internal processes, SOP and knowledge about our areas of expertise.
Resources

Definition: Topics or interests that might useful in the future.

 

Akvo: This is where we compile useful links and documents, reading lists, list of conferences, etc...
Archive Definition: Inactive items from the other 3 categories.

Content Nesting

BookStack offers 4 levels of content nesting:

  • Shelves - Used for content categories (PARA).
    • Books - Used for top level content grouping.
      • Chapters - Used to organize low level content elements.
        • Pages - Used to organize low level content elements. Note that pages can also be directly below a book.

Default Organization

Projects / Products

Each project has a dedicated book, with the following structure:

  • Project Sheet (page) - A table providing essential information about the project. Use the Project Sheet template.
  • Technical documentation (chapter)??

Each product has a dedicated book with the following elements:

  • Product Sheet (page)
  • Technical documentation (chapter)??

Areas

Each support team has a dedicated book.

Archiving Content

To archive content you simply need to move it to the Archive shelf. Make sure to add the [archive] prefix to the title of every archived content (book, chapter, page).

No Comments
Back to top