DEV Community: Fabrizio Traversin

Documize

Fabrizio Traversin — Wed, 29 Jul 2020 13:16:03 +0000

As I wrote in my previous post, I am evaluating some tools for writing documentation. First of all i tried Documize, here a share my opinion.

How does it work?

Documize defines itself like "Team-driven content authoring & automation for secure internal and external documentation".
It's written in Go and Ember JS and it's an open-source project, you can find the source code on Github repository.
You can choose between the Team or Enterprise Edition, and for the Enterprise you can choose the Cloud hosting plan or the Server Installed one (self hosting).

In Documize the "document" consists of a group of "sections" and each section can contain a type of content typed or it can embed content from external tools. You can edit and rearrange every single section, which is indexed, and you can easily get a "summary" automatically. So you can easy write a rich text (using WYSIWYG tool) or embed a code snippet or put a diagram for technical documents. Every changes is traced, so you can roll back any time.

What I like

Clean Output

Once you've finished to write your content, you have a clean and very pretty output, organized and easy to manage.

Automatic Word Import

This is my favorite one. We have tons of doc files in any folder of our servers or other search-less locations and we spend a lot of time searching for the wanted file. And sometimes we cannot find what we want. This is a big lack in our company. For this reason this tool is so appreciated! You can easy import doc files and Documize works for you re-structuring the text in paragraphs magically. You only need to adjust something for improving the final result. Step by step the "porting" process from our docs to Documize become very easy.

Attachments

Uploading files as attachments, become very useful, especially in the porting process to Documize (see previous point), because you can easy check the original document any time and perform a better control.

Subdomain

If you're interested in publishing public documents, this feature become very useful, because you can easy share a link with your company (account) name. You can simply have your own landing page with all your public documents (cloud plan).

Public Spaces

If you are interested in sharing documents (such as, tutorials, technical documents, etc.) with your customers, you can set up public spaces where to place your documents, for easy sharing. In public spaces it is not necessary to set up user groups, or let your customers register to any kind of service.

RichText (WYSIWYG)

Documize has a very powerful and complete "Rich Text Box", where you can put also tables, code snippets, insert and edit images and videos. The tables are also very customizable, so it is very simple to create what you want.

Diagrams

For me this is a big plus. You can easy draw diagrams using "PlantUML" or "Draw.io" tools. Especially draw.io (now diagrams.net) for me is the best online diagram tool, with very rich utilities. If you work in a tech company it's a "must have" to draw flow charts, system flows and all kinds of diagrams you need. This tool is very well integrated, so it makes you feel comfortable creating diagrams.

Revisions & Versions

You can have the revision list and the activity list of every document, with the possibility to restore each version at the wanted revision.
Also you can set a document version (different from content revision) which let you write a brand new document. This could be interesting if you're writing documentation about a product which have some new features or updates.

Self-hosting

Sometimes a cloud solution may not be the right choice, especially if a company relies heavily on the security of its data. Documize has a self-hosted version that can be installed on your server, behind your firewalls and your security rules. However, the self-hosted plan is very expensive. Also you can have an hybrid hosting solution.

Enterprise Free plan

The enterprise edition is completely free for up to 10 users, so private or small business accounts can manage their documentation for free.

Links

You can publish and create a link for each section. So if you need to share only a part of a specific content, you can easily do it by getting and sharing the link.

Comments

In every document, you can leave comment and you can choose if applying it to the entire content or to a single section.

Integrations

Trello, Jira, AirTable, Papertrail, Gemini, IFrame. You can have the best integration modules and, if you are a developer, API services to customize your Documize experience. Maybe in the future the list will be extended.

Reports

Finally you can have an overlook of your documentation, with simple reports. They're not so cool, but they're useful.

What I dislike

Only 2 grouping level

Yes. You only have 2 levels to group documents: spaces and documents. It's not a big deal, because you also have tags and categories to set on each document, but if you have a large and structured company, an extra grouping "folder" would be appreciated.

No "real" themes

Themes in Documize concern only the customization of the color of the toolbar, they are not real themes to be applied to your documents to show them in a different style. A "dark mode" would also be appreciated, especially if you write a lot.

Export only in pdf or html

Sometimes it is necessary to have more possibilities to export and share the documentation, also using different channels, such as the possibility of publishing documents also on other platforms.

Slow internal links

Internal links are slow. You can get a link for each section, but it's not easy to manage. Also I don't like the interface, I think it's not clear, I took a lot to understand where they were.

No auto save

This is the worst for my experience, especially when you're writing long contents. For example, you can go in "edit mode" for each section of your document, without the need to close/save the current "working section". So sometimes, if you unfortunately forget to save all opened sections you can easy lose your job. You just need to browse the previous page and lose your content. The best practice is to edit only one section of content at a time, but sometimes you still risk losing data.

Settings Interface not clean

Sometimes you are looking for an option to set, a tag or a category or any other type of setting, you feel confused because you don't know where to go. The interface should be improved, so that you have the things you need close at hand.

Not automated self-hosted installation

Okay, this isn't a big lack, most people use the cloud version for sure, it's easy. But if you want to test the self-hosted version, you have to follow the guide step by step and be expert enough to install the required services.

No app for writing offline

If you're using the cloud service you must to be connected. An app for writing offline with a sync service could be useful for a lot of users.

My vote:

8/10

Writing documentation

Fabrizio Traversin — Fri, 24 Jul 2020 13:35:55 +0000

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

Nim strings

Fabrizio Traversin — Sat, 15 Feb 2020 20:55:02 +0000

Nim Programming Language

Nim is a brand new and very charming programming language, so a couple of months ago i decided to start to study it in my spare time. So i took some notes and examples, i hope they could be helpful to someone else.

STRINGS

"Strings" is a builtin data type in Nim, so you can use it always (module declarations is not necessary).

Declaration:

you can declare MUTABLE or IMMUTABLE strings.
Use let for immutable string declaration.
Use var for mutable string declaration.

Simpler declaration:
you can declare string variables taking advantage of the compiler type inference: it's not necessary to declare the "string" type, because the type will be resolved by the compiler.

# Simply declare let/var, variable with '=' operator and the string between double quotes 
let si = "This is an immutable string"
var sm = "This is a mutable string"

echo si   # -->  This is an immutable string
echo sm   # -->  This is a mutable string

You CANNOT re-assign an IMMUTABLE strings.
This will cause a compiling ERROR:

si = "Trying to re-assign an immutable string"

# COMPILING ERROR!!!
# Error: 'si' cannot be assigned to

You CAN re-assign a MUTABLE strings.

sm = "Re-assigning the mutable string"

echo sm   # -->  Re-assigning the mutable string

Explicit Declaration:
you can choose to declare the string variables, without the use of the compiler type inference. Simply you have to declare the "string" type after the variable name and the ":" operator.

# explicit string declaration
let siexp:string = "Another immutable string"
let smexp:string = "Another mutable string"

echo siexp   # --> Another immutable string
echo smexp   # --> Another mutable string

Multi-line strings:
for declaring a multi-line string just write the string text between a triple "double-quote"

# multi-line string declaration
let mls = """This is 
a multi-line string,
you can use it for html code
or just for christmas tree! ;-)

    *   
   ***
  *****
 *******
*********
    |
"""

echo mls
# -->  This is
#      a multi-line string,
#      you can use it for html code
#      or just for christmas tree! ;-)
#
#          *
#         ***
#        *****
#       *******
#      *********
#          |

Unicode glyphs:
in Nim the strings contain text, encoded with the UTF-8 format, but also Unicode format is allowed. So you can use some 'Rune' type (glyphs) in your text.

# string with unicode characters
echo "This is a string with unicode characters: ℛ ₪ ⎒ ♥ ♫ ☻"
#---> This is a string with unicode characters: ℛ ₪ ⎒ ♥ ♫ ☻

Raw strings and escape characters:

there are some "special" characters, which have a particular meaning, especially in text formatting. They're called "escape characters" and they're always preceded by the '\' character. To "bypass" the string interpretation, you can use the raw string format, just putting 'r' after the opening string double-quote.

# string with \n (newline character):
echo "This is the first line...\n...and this is the second one"
# ---> This is the first line...
#      ...and this is the second one

# string with \t (tab character):
echo "This is the first part of the string\tand this is the second one"
# ---> This is the first part of the string    and this is the second one

# string with \\ (backslash character):
echo "This is the path-string: c:\\folder\\inner-folder\\"
# ---> This is the path-string: c:\folder\inner-folder\

# string with \" (quotation mark):
echo "This is a string with \"double quote\" in the text"
# ---> This is a string with "double quote" in the text

# bypass escape characters with a raw string:
echo r"This is a raw string: escape characters like '\n' '\t' '\\' are not interpreted"
echo r"In a raw string you can write 'c:\program files\nim\' instead of 'c:\\program files\\nim\\'"

# ---> This is a raw string: escape characters like '\n' '\t' '\\' are not interpreted
# ---> In a raw string you can write 'c:\program files\nim\' instead of 'c:\\program files\\nim\\'

Concatenation:

You can join only strings with strings.

# Concatenation with '&' operator
let s1 = "This"
let s2 = "string"
echo s1 & " is" & " a" & " concatenated " & s2
# -->  This is a concatenated string

# Appending string with 'add' method
var stradd = "This is a string concatenated"
stradd.add("...with .add() method")
echo stradd
# ---> This is a string concatenated...with .add() method

Lenght:

# string.len() / string.len: return the lenght of the string
var l = "The lenght of this string is"
echo l, ": ", l.len()
echo "this is 11!".len
# ---> The leght of this string is: 28
# ---> 11

Comparison:

# Comparison by lenght, using operators '<', '>', '<=', '>=', '==', '!=':
# A true/false value will be returned
let
  s1 = "This string has some characters"
  s2 = "This one has few chars"
  s3 = "This string in longer than others, because it has a lot of characters"
echo s1 > s2   # --> true
echo s3 <= s1   # --> false
echo s2 == s3   # --> false
echo s1 != s3   # --> true

Casting:

# $<var_name> --> str: transform a value in a string
let numint = 123     # integer
let numflo = 0.987   # float
let s = $numint & "-four-five-six-" & $numflo   # string concatenation
echo s   # ---> 123-four-five-six-0.987