Documentation System

In this article we describe the reasons for choosing the GitBook as our documentation system.

Based on our research we have three major approaches for documentation system. First is using a collaborative online system, second is using a modern wiki or markup system, and the third approach is just using the old wiki systems. here we are going to have a survey on these.

Collaborative online systems

In these systems we have full control of our project. including project management tools, task management, calendar, chat systems, etc. In other word, in these systems we have a lot of features and a lot of abilities to do what we want. for summarizing major features that we have in collaborative online systems are:

• Plan
  • Create user stories and issues, plan sprints, and distribute tasks across your software team.

• Track
  • Prioritize and discuss your team's work in full context with complete visibility.

• Release
  • Ship with confidence and sanity knowing the information you have is always current.

• Report
  • Improve team performance based on real-time, visual data you can use.

• Knowledge management

  • Documentation system that is integrated with all project

• Development workflow

  • Version control system and automatic change tracking

• Real-time collaboration

  • Keep your team in the know

Some example of these systems are:

• Atlassian JIRA
• Bitrix24

But the weakness of these systems is its strongness. because of the main goal of these systems and their complexity and over features of them, we don't choose these systems.for summarizing:

• Too complicate
• Take a lot of time to lean theme well
• Pricing of course is important factor. most of them doesn't have a suitable free plan

Modern Wiki or Markdown

In these systems the focus is just documentation and this is a very positive point. this specific and single goal system is perfect for us. because these systems are designed for documentation so they have a lot of good features. another good point of them is ease of use and fast learning capability. for summarizing :

• Easy to use
• Easy to learn
• Specifically for documentation
• Several format supported like Markdown, HTML, PDF, etc.
• Real-time collaboration and documenting system
• Version control and revision history is supported by some

some example of these systems are:

• Atlassian Confluence (Captain in this category)
• Nuclino
• StackEdit
• HackMD
• GitBook

all of theme have great features but the GitBook is our choice for

• Documenting style

  • It's like a book. has cover, glossary, partition system

• Good markdown editor with great ui

• Good desktop editor

• Web export ready

  • your book is always can be read from your Url address.

• PDF export ready

• Can be synced with GitHub project

Unfortunately Confluence doesn't have any free plan. if you can afford to buy a plan, you should choose this option.
Nuclino was good too, but for a lot of connection problems and not as good document style as GitBook we don't choose this. Rejecting StackEdit and HackMd options was not a very hard job. because of their lack in documentation management for a complete project. they are just for real-time working on a specific document.

And in the end, because we find a good choice we doesn't investigate the third option (they obviously have less features than something like GitBook). Finally, we choose GitBook as our documentation system.