Documentation Writing Organization Effort

Is there a place to organize documentation-writing efforts?

Where can I get started? Perhaps this already exists someplace and I just don’t know about it. I’d like to try and help write documentation so that people will complain about it less often.

3 Likes

I’m not aware of any! Maybe this could be it :)

1 Like

Maybe a Wiki: wiki.crystal-lang.org?

I think it’s about coordinating efforts on improving the existing documentation, not a place for a kind of documentation :)

1 Like

Yes, exactly. I think for now, this thread is fine.

The process I had in mind was roughly:

  1. Collect a bunch of places that people complain about, or that don’t currently exist.
  2. Allocate people willing to take a certain section of that work.
  3. Write it, and whatever else happens via git.

There’s plenty of confident Crystal users, there’s plenty of people who want better documentation, so hopefully this isn’t a hugely uphill issue.

My current take is to create sections as described in https://github.com/crystal-lang/crystal-book/issues/384#issuecomment-593409984 .

I think is not only about documenting how things work but about organizing the content to introduce content at a phase the reader will find useful, but not overwhelming.

I don’t have proposal regarding the how the different articles could layout. It would be great to have for each article some description like:

  • why the reader should read this article?
  • what the reader should know already?
  • what will the reader be able to do after reading the article that he/she wasn’t able before?
  • Is there follow up material in case more details are wanted?

I imagine from there we can layout the relationship of the content before jumping in and writing it.

I’m open to suggestion in what could be a good process to have that discussion.

@wrq your suggestion to collect complains seems to be also a good asset to have in hand for the content planning.

1 Like

Oh wow, I didn’t know there was a repo for the book, I totally should have looked!

Right, so I completely agree that the layout of the book could be improved and offer a better navigation experience for users of different skill levels. I took a peek at Rust’s “Learn Rust” page and I think it’s a wonderful format for guiding users, with maybe room for a slight improvement.

The page is a huge text “Learn Rust”, with three sections for different learning material. First the language manual, obviously a sensible choice. Then, the Rustlings course, which seems to be something similar to like Ruby Koans, if yall remember that. Then, there’s the Rust By Example book, which is a separate manual that dwells on semantics and structure of applications rather than the nitty gritty syntax and control flow stuff that so many manuals are filled with.

Later down the page, which you’re naturally inclined to see because the content cleverly starts halfway down the page load from the beginning, there are links to the Std api, and the dozen or so other book that have been compiled from various sub-sections of the ecosystem.

Granted, rust is a big overcomplicated, difficult-to-learn language, and is funded by a very large corporation, so it’s not like Crystal docs are gonna have 10+ books written about them in the near future. Still, there are things to be learned about how that page flows, and I think in particular that UX experience is lacking on the crystal-lang.org/docs page.

As far as arriving on a discussion format, I’m not exactly sure? I think there ought to be a subforum here on discourse for reasoned conversation about documentation in particular, and maybe there should be like a poll or something. The crystal-book repo may also be a decent place to have discussions, if there’s an easy way to facilitate that sort of thing.

I’m very curious about the way people use the documentation:

  • Do they know ruby and just need type signatures and compiler recipes?
    • As an aside, I wish there was a way to search specifically for the return types of methods. I don’t wish it so strongly that I’d like to write my own search tool for it, just that it might magically appear.
  • Are they skilled programmers, or beginners?
  • Are they looking for examples, method names, what format of help were they hoping to find?

I’ll be searching through the forum and trying to find out what experiences beginners are having with the documentation that exists today, and maybe get an idea for the “average” user.

Aside from all this, I’m an advocate of there being a Crystal By Example resource somewhere, and I’d LOVE to be a part of that.

Consider this in the process.

1 Like

It’s a very thought-provoking article, I enjoyed reading it.

Sadly, there weren’t any diagrams or examples to behold.

I was curious if you might have some advice about where Crystal docs could use diagrams? Is there any place in particular that needs them as a priority?

I’m not a very good visual thinker, I would struggle with making a diagram, and so I could probably find somebody else to help make some if we had some concrete ideas.

Thanks for sharing this! :slight_smile:

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

I’m very curious about the way people use the documentation:

I can talk about my own experience as a Crystal newbie with decades of experience in languages like C/C++, Perl, and various assemblers and to a lesser extent languages like PHP or javascript:

I found the docs plentiful but terse and lacking examples. The feeling I had was that the docs might get more useful in the future when my Crystal knowledge reaches the necessary critical mass. In an effort to increase my knowledge, I found the Crystal forum not so responsive to my questions. But I found both gitter chat and github issues very responsive.

The problem is that answering my questions on gitter is great for me but doesn’t act as a potential resource for other newbies in future months and years, and so I created the following docs request / suggestion [1] which unfortunately wasn’t received very well, but I’m posting it here for completeness, and because the general issue of docs is being discussed here.

I’m an advocate of there being a Crystal By Example resource somewhere, and I’d LOVE to be a part of that

Me too! I’m not married to my suggestion at all, but I would welcome any effort which results in a lower friction way (i.e. not higher friction like making PRs to official Crystal docs) to compile some kind of Crystal By Example resource.

Granted, rust is a big overcomplicated, difficult-to-learn language, and is funded by a very large corporation, so it’s not like Crystal docs are gonna have 10+ books written about them in the near future.

Yeah, and I think this is why it’s important for the Crystal project to somehow leverage the community at large to create the examples and blurb about them, without expecting them to produce professional docs. For example, wikipedia has a discussion page for every ‘official’ page it publishes… why not have something like that for Crystal?

[1] Feature request: Add 'User Contributed Notes' to Crystal docs · Issue #9375 · crystal-lang/crystal · GitHub

1 Like

In my opinion one simple example tells much more than a lot of detailed explanation (which still nut hurts though :slight_smile: )

4 Likes

yes, a wiki like https://rosettacode.org/wiki/Reports:Tasks_not_implemented_in_Crystal. Everyone can edit the document.
How about to only show the raw official document and fold the lastest document which edited by anyone at every point like method or other, if I want to read the latest modify, just need to unfold it ?

One thing that should also be held in mind for improving docuementation / reference is making sure search works appropriately.

For example I wanted to know the difference between include and extend, and so in the reference I search for the word include. It returns no results, when actually the difference is clearly stated in the Modules section.

Furthermore in the vein of learning crystal by example, that’s exactly what I’ve been doing via Lorenzo Barasti’s video series. It’s been so useful, I can see how creating similar text-based resources could be helpful as well

1 Like

One example is better than asking the same question 100 times in Gitter. Especially for people who do not have a sufficient level of English to follow a discussion that strays from the initial question.

A Wiki will be awesome and accessible. To contribute in a Wiki the process is simple and fast.

Also some examples in the official API doc will be productive.
I will gladly contribute. :slight_smile: