Ramtin

Let's share the best of our coding knowledge

A different approach to writing documentations

As a web developer I often find myself documenting my code, especially in a work environment where my co-workers need to fully understand what’s going on in the code I wrote in order to participate. In those cases where the documentation will be read by developers and not users (meaning documenting the whole source code and not just the API), the usual approach of writing documentations with markdown, breaking topics by headers and providing code examples is not quite efficient for massive libraries since it’ll leave us with a very large documentation which maintaining it would be a time-consuming job.

For example, in my latest project, I was working on a monstrous Node module with too many nested objects and I needed to document every object, function, closure, and the idea behind them so when my co-workers and I would come back to them for debugging or when we would use them in different places, we’d know exactly what’s going on inside the code. Before I’d even start writing the content of the documentation, I realized that it’ll take a good amount of time to write, and another good amount of time each time we’d want to find some part of it to read or update. So, I tried to make it easier by creating an index at the start of the documentation, but for starters, the relative links to anchors inside the documentation (link to headers) wasn’t working which is a current bug/shortcoming of the atom-markdown package, and on top of that, the list ended up being as long as the height of mount Everest! So clearly, I had to find another way…

I was able to find an Atom package which allowed me to use a whole different approach for writing my documentation, and it was so efficient that I decided to write a post about it and share it with you all. What I found is called foldingtext-for-atom.

foldingtext-for-atom is an outline editor available as an Atom package, which is part of the FoldingText markdown text editor project. This package gives us the ability to create folding outlines with some text formatting. Using this package, I wrote my documentation in a very efficient manner which ended up saving me and my co-workers a lot of time when reading and maintaining it.

Below are the steps of how to take advantage of the abilities this package provides to write an efficient developer documentation.

Installing FoldingText Atom Package


We can either install this package through APM (Atom Package Manager) by running apm install foldingtext-for-atom in console, or simply searching for foldingtext-for-atom through Atom Settings (cmd + , / ctrl + , > Install > foldingtext-for-atom).

After installation, we can create a new FTML (FoldingText Markup Language) document from File > New Outline.

Package Overview And Shortcuts


With the new outline opened, we can now use the benefits of this package:

  • Every outline can be expanded and collapsed to either show or hide its child outlines, thus saying goodbye to mount-everest-long index lists in markdown!
  • We still have few of the markdown formatting (though not through markdown syntax), such as italic, bold, underline and strikethrough formatting (though the last two are not part of CommonMark definition).
  • We can add as many tags as needed to each outline.
  • There are four status tags which we can apply to outlines: todo, waiting, active and complete.
  • We can determine the priority of each outline with priority tags ranging from 1 to 7.
  • There are more stuff which can be read about through their documentation, but that’s all the features we need to start writing our documentation.

Here’s a quick look at the shortcuts we need:

MacWindowsDescription
cmd + bctrl + bFormat bold
cmd + ictrl + iFormat italic
cmd + uctrl + uFormat underline
cmd + kctrl + kFormat strikethrough
ctrl + cctrl + cClear formatting
tab, cmd + ]tab, ctrl + ]Indent one step
shift + tab, cmd + [shift + tab, ctrl + [Outdent one step
cmd + .ctrl + .Expand/collapse outline
escescSwitch text/outline mode
t, cmd + shift + tt, ctrl + shift + tEdit tags (first shortcut only in outline mode)
s + ts + tSet/unset todo tag (only in outline mode)
s + ws + wSet/unset waiting tag (only in outline mode)
s + as + aSet/unset active tag (only in outline mode)
s + c, cmd + spaces + c, ctrl + spaceSet/unset complete tag (first shortcut only in outline mode)
cmd + upctrl + upMove line up
cmd + downctrl + downMove line down
1, 2, … , 71, 2, … , 7Set/unset priority (only in outline mode)

Documentation Structure


The structure of the documentation plays the greatest part in its effectiveness. The documentation structure should be exactly the same as the code structure. Let’s assume we have the following library that we want to document:

The library is called Recruiter and provides a simple algorithm to match people with jobs. It also has a factory object which generates person and job objects. Let’s copy the above code into a new file and have it opened in Atom on the left pane, while having our new Outline file opened on the right pane.

atom1

The first step of writing our documentation is to create outlines following the structure of Recruiter module. Let’s add the outlines:

atom2

Make sure you know the shortcuts so you can quickly follow along.

Giving Text Formatting Meaning


The next step is to use text formatting to differentiate the nature of outlines and the type of information they represent. What formatting to use to reflect what type of information is totally up to you, but I use the following setup:

FormattingMeaning
boldMembers that are exposed to user, thus defining the API.
italicClosures.
strikethroughDeprecated members that are subject to change and shouldn’t be used.
underlineOutlines that exist only on the documentation level and are not part of the actual source code.

Let’s use the appropriate formatting on our outlines:

atom3

Next, let’s define some documentation outlines using underline formatting to provide information for each outline. Again, this is totally up to you but the key is to follow a pattern when adding those documentation outlines, meaning using fixed keywords for each type of information:

KeywordUsage
descriptionProvides a description of usage for its parent outline.
argumentsProvides a list of arguments that its parent outline has defined.
returnProvides information about the return value of its parent outline.

Also, appending () to outlines representing functions can make them pop so we would instantly recognize them being a function.

Let’s add the parenthesis and documentation properties:

atom4

After adding all the documentation properties, we should be left with something similar to this:

atom5

Tags As Properties


By now, our documentation is formed and contains information about how each member works, the inputs and the outputs of functions. The next thing we want to add to our documentation to reflect more information is the type of each outline. We can use tags to determine the type of each outline (function, object, string, boolean, etc.) and the properties/behaviors of each (closure, required, optional, etc.) which gives us the advantage of filtering our documentation based on types.

To add tags to our outlines, first press esc to go into outline mode, and then press t to show the tag dialog. Then write the name of tags and separate them with spaces, and finally press return to add the tags.

Let’s add some tags to indicate outlines type:

atom6

After adding all the tags, we should be left with something similar to the following:

atom7

Making Use Of Statuses


FoldingText provides four status tags: active, waiting, todo, and complete. Let’s use the first three to indicate the state of each function:

StatusMeaning
activeIndicates the member is functional and has been fully tested.
waitingIndicates the member is fully written but has not been tested yet.
todoIndicates that the member is half-functional or non-functional and shouldn’t be used yet.

The reason we don’t use the complete tag is first because we have an equivalent tag active to show functions completeness, and secondly because the complete status applies strikethrough formatting to our outline which we use for deprecated members. Also the complete status has the same color as other normal tags and has a # before it, which makes it hard to be differentiated as a status.

We add statuses to outlines by first pressing esc to go to outline mode, and then pressing s for status, followed by a, w, or t for active, waiting, and todo respectively. To remove a status, simply apply the current status again to remove it.

Now let’s assume the following scenario for our functions:

FunctionStatus
factory.person()Is functional and tested.
factory.job()Is fully written but not tested.
addJob()Is functional and tested.
recruit()Is yet to be written.

Let’s use statuses to reflect this scenario:

atom8

Task Management


Still not using complete! But just by using the other statuses, we’re achieving two purposes, first is to inform the readers what function to use and what to avoid, and second is to inform the contributors what to work on and what is complete/active.

There’s one more feature that we can take advantage of, and that’s priority tags. They range from 1 to 7 and can indicate the priority of our todo and waiting statuses. This part is for the contributors only.

To set the priority for an outline, press esc to go to outline mode, and then select any of the buttons 1 to 7 for the relevant priority number. To unset the priority, apply the current priority to the same outline to remove it.

Let’s set the priority of recruit() to 1 and factory.job() which only needs testing to 2:

atom9

After we’re done with our library, we can remove the priorities and change todo and waiting statuses to active.

Add A Legend


The last thing to do is to add a legend for our readers to provide information about how we’re using formatting, tags, statuses, and priorities to reflect different information. Since legend would only exist at the documentation-level, we should underline it like we did description, arguments, and return outlines.

The legend should be at the top of the documentation and should look similar to this:

atom10

The Result


After going through all the above steps, we’re left with an outline-based documentation which has in-depth information about our library, and is super fast to find the portion of information we need at the time because of it’s identical structure to our library, something that could have never been achieved by a regular text-based documentation.

It’s definitely meant to be read by developers and not users, and having it opened on a split pane speeds up the process of understanding how to use a library for developers and contributors.

Let’s use our library and read the documentation at the same time:

atom11

See how fast it was to find the information we needed? Try it on a library with 5000+ lines of code! It gets more efficient and convincing as the library scales.

That was how to write outline-based documentations with FoldingText Atom package. Read more about FoldingText package and FoldingText Standalone App. If you liked this post, please share it with the people you know who can use this information.