Documentation Guidelines

Our wiki is based on the Open Source application called BookStack. Check the 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.

Please always 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 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.

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.

Project sheet

Archiving things

Templates

Useful BookStack Features

BookStack offers a lot of useful features that will help you create beautiful documents in a very efficient way. Here's a list of the most useful features.

Feature	Description
Keyboard Shortcuts	Most formatting options have a keyboard shortcut that allows you write most pages directly from your keyboard.
Code Blocks with Syntax Highlighting	Many languages are supported. Example `program hello write(,) 'Hello, Akvo!' end program hello`
Diagrams, Drawings & Math Formulas	You can create and insert diagrams, drawings and even math formulas (LaTeX) using the Diagrams.net application. There's even support for Mermaid. Examples
Collapsible Blocks	Collapsible block are useful display content on demand, in particular for long pages. Example I Dare You To Open 👺
Table Formatting	You can pimp your tables with header and footer rows. See this table as an example.
Full Screen Mode	For distraction free writing you can toggle the fullscreen mode.
Templates	You can mark a page as a template so that its content can easily be reused when editing and creating pages. This can be super useful when you need to create many pages following a similar format. See official documentation.
Webhooks	You can configure webhooks from BookStack in order to perform POST requests to other services. Many (if not all) application events can trigger a webhook.