Documentation Writing Organization Effort

Community
10

I’m glad you took the time to read the article and found it useful.

Diagrams are not just drawings|graphics, but any visual means of information presentation.

A quick specific example is code annotation of Humble numbers

In the code I commented on the speed difference between using a tupple|{} vs an array|[]. A tupple exists on the stack (memory) while arrays in heap (memory).

This can be pictorially shown with diagrams of how the stack works (LIFO) versus the heap.

Also, the docs can have a section that has a table of stack vs heap operations.

         Stack      |     Heap
--------------------------------------
   tuple - {...}    |   array - [...]
          ....      |      ....

The key thing to always remember when creating documentation (for anything) is to be clear on, 1) what is the (Crystal) story you’re trying to tell, and 2) who is/are the intended audience.

  1. This is most important. What is the story about Crystal you intend to present. There are many potential stories to tell, so you first have to be clear on which ones you want to present.

  2. How you tell the stories depend on the particular audiences you’re telling them to.
    The story for compiler writers and code developers will be different than for code users, and even more specific depending on where those users are coming from (Ruby, C/C++, newbies, people with disabilities, non-english speakers, etc). This requires allot of empathy to put yourself in the shoes of the many people who will read your stories.

The really good thing is you don’t have to start from scratch figuring out how to do these things, and there are many existing resources available to help. I provided many in this thread.

An efficient way to start is by looking at documents|websites for various projects and see what you think are good. But first create an objective metric of criteria (e.g. code examples coverage; keyword indexing; cross-referencing; use of videos, diagrams, tables; language translations, etc).

First start by looking at other languages, e.g. Ruby and Python, etc, to create a baseline of what’s out there (good to bad).

But also check out other technical sites. I particularly love how Quanta Magazine presents its articles content with visuals and diagrams.

Finally, creating good documentation is an art that requires skills. The are loads of Open Source resources to aide the process, with tons of skilled people to assist.

Start small first (just up[date|grade]) with the existing docs, while formulating a grander vision.
The key thing is just start.

1 Like