Writing documentation

ftraversin

Fabrizio Traversin

Posted on July 24, 2020

Writing documentation

Differences among software for team wiki, project documentation, knowledge base, tech documentation, and other authoring tools

What tool?

Since long time i'm looking for team collaboration software for writing documents, easy to use, reliable and also usable for "non-technical" people. At the beginning, i started to write technical and knowledge base documentation for my company with dokuwiki, and i love it, but you need to learn the syntax, and a lot a times you cannot force someone of your team/company to learn something just to write "simple" documents. So, i made a very nice and useful wiki site, but i was the only active maintainer. Also you need to know how to install the wiki site, how to update, how to install modules and so on. However you can have a pretty, free and self hosted wiki site, with the user access control (you decide who and what can read/edit/create pages) and the revision history of the pages.

The next step was trying other "static site generator" tools, like daux.io, mkdocs.org, readthedocs.org, github pages, gitlab pages, and other tools mainly based on markdown syntax, but sometimes it's hard to set up the necessary environment to generate html pages. Also writing in markdown is not a good choice for me...

Finally i tried more specific tools like Confluence... and it's for sure one of the best, but the first impact could be "too much" and leave you like a fish out of water. Then i focused on easier and similar tools and i chose to valuate Documize, Bit.ai, Archbee, Tettra and Slite.

My mainly targets are:

  • Centralized documentation: one single place to search what you need.
  • Collaborative tool: users/teams should write and manage their own documents and share them easy.
  • Easy writing: every employee should write without a particular knowledge (WYSIWYG)
  • Cross purposes: marketing, company knowledge base, best practices, on-boarding, know-how, customer tutorials, technical documentation
  • Document revision history and versioning.
  • Diagrams tool for easy flows representation.
  • Code snippets: for sharing coding examples among software developers. The next few days I will publish my evaluations here.

How does it work?

The concept behind this kind of tools is the section or "smart embedded block": every document is made as a list of indexed blocks and every block represents something: a text, a code snippet, a diagram, a map, a table or other utilities. Every block can be moved inside the document or in other spaces, and also can be cloned. So you can re-order the information as you need and have an auto-generated table of contents in a easy way.
Every document is grouped in a space, which define the main argument. For example you can have some private documents grouped in the space for marketing, others in the space for the company knowledge base and a public space with technical documentations for your costumers. You can also set categories and tags for a more simple search.
Also, you can define user groups and control the access to the documents or spaces.
Once you finished to write, you can easy publish or export documents in pdf or other most used formats.


First of all i tried Documize and I will share my evaluations about it in my the next publish.

And what about your favorite tool in writing documentation?

[edit] Published Documize Evaluation

💖 💪 🙅 🚩
ftraversin
Fabrizio Traversin

Posted on July 24, 2020

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Writing documentation
content Writing documentation

July 24, 2020