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 >- Books > Chapters > Pages. Shelves are usedUsed for content categories.categories (PARA).
  • Books are- usedUsed for top level content grouping. This
    means
    • Chapters that- youUsed can use Chapters and Pagesto organize yourlow content.level content elements.
      • Pages - Used to organize low level content elements. Note that apages pagecan does not have toalso be indirectly below a chapter.
        book.

Project sheet

Archiving things

Templates

ContentUseful FormattingBookStack Features

It is important to produce documentation that is pleasant to read. BookStack offers a rather clean theme and a setlot of useful features that will help usersyou navigatecreate properlybeautiful documents in a very efficient way. Here's a list of the wiki.most Youuseful should use BookStack feature whenever possible.features.

UseTheDefaultHeadings

Feature	Description
Keyboard Shortcuts	ThereMost areformatting 4options levelshave ofa headingskeyboard shortcut that canallows beyou used.write Headings are used to create the table of content formost pages thatdirectly isfrom displayedyour onkeyboard. left pane.   Mastering BookStack
Code Blocks with Syntax Highlighting	Our wikiMany islanguages basedare onsupported.     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 OpenDiagrams.net Sourceapplication. applicationThere's calledeven support for BookStackMermaid. It provides a wide range of use features that you would expect from standard wiki software, and more. Code Blocks   DiagramsExamples Templates
Collapsible Blocks	Collapsible Blocksblock are useful display content on demand, in particular for long pages.     Example   I Dare You To Open Me 👺
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.
API & Webhooks