DEV Community

loading...

Writing documentation

Fabreath
Self-taught developer, I like learning new programming languages. #python lover, #rust & #vlang student. Now I have a crush on #nim & #pony
Updated on ・3 min read

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

Discussion (2)

Collapse
esnz profile image
josias enoc saenz • Edited

Hey man, I know is a bit late
but have you tried HACKMD? not so cool interface but gets the job done
also WikiJS is a good project to keep an Eye on

I´m also looking for a collaborative Wiki/knowledge base with git WYSIWYG
gorgeous UI diagrams how to tutorials, and maybe if possible realtime (or maybe not) collab and comments

after 6 months searching no product satisfied me
so I ´m thinking of making one my self

A headless CMS with graph or Rest api could tremendously speed up the backend so you can focus on the front end

If you are still on the hunt, I strongly recomend you Strapi or Cockpit or Directus or ApostropheCMS
just make a frontend with api calls to the headless cms and you are good to go in a few days
fully customized

Collapse
fabreath profile image
Fabreath Author

Hello! Thanks for your answer and for your suggestions!
I have never tried HACKMD, I will for sure.
WikiJS is a very nice project, I'm following it on github ... I'll see

I agree with you, there are many alternatives on the web, but none are completely satisfactory. Now, at the company where I work, I'm still documenting with DokuWiki ... but it's a good alternative only for tech writers, despite the WYSIWYG module. I really like Slite and Notion, but I'm not convinced.

The idea of developing something from a headless CMS is good, but at the moment I would prefer to use something ready.