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

meansChapters 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.

Use

TheDefaultHeadingsFeature 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