Making Documentation Better

Introduction

I want to present here my ideas on specific actions Crystal can take to greatly improve its documentation, thus making it significantly more attractive for people considering it, and more useable/practical for people coding with it.

Impetus comes from my comments made in this thread that I want to expand upon in a structured manner, to emphasis that documentation should be just as much a priority for the devs as code development is.

Good Documentation Matters

It has been stated over and over and over documentation is vital, and will even make or break a project, but it will still be overlooked, or even thought of with disdain, by developers. But not by users.

There’s even a whole field of how-tos to help, like this and this, ignored by real projects.

One project (made aware of via Rosetta Code) which I feels gets it right is Sidef which has very functional documentation, which I suspect has fewer (people) resources than Crystal.

Documentation Can’t Be An Afterthought

No matter the technical proficiency of a project’s developers, if potential users don’t (quickly and easily) understand how to use it, it won’t get used. Rust continually faces this problem, no matter how well it’s rated technically.

TODO:

Use The Force Luke, e.g this. There are many resources to help, pick at least one and use it.

If It’s Not Accurate It’s Not Documentation

From a user’s perspective, the worst case scenario is inaccurate or outdated information that results in unworkable code, which in many cases can’t easily be debugged. If a user is forced to consult third party sources (Stackoverflow, etc) to figure out why code doesn’t work, or how to do something to get working, then the docs have failed.

TODO:

Whenever changes/updates are made document them before they’re publically announced. Inaccurate and outdated information should never be presented to the public. Assign each dev some section(s) of docs to maintain and update as a required responsibility .

Blogging

The Blog should be used as a primary means to educate current (and potential) users on specific coding issues and project changes.

TODO:

Make frequent (short) posts, on specific issues/topics beneficial to users. Use issues raised in forums, etc, as their sources. Create index/tag system to easily identify/access them.

Create Specific Ruby Compatibility Section

If you tout Rubyness show how compatible Crystal is with it. Acknowledge since Ruby is the senior language the natural source of many/most Crystal users will/should come from Ruby.

To this end, (and I know there’ll be resistance to this) make Crystal as similar to Ruby as possible while still pre 1.0. Do differences e.g. includes?|include?, etc, really need to exist? Make the compiler accept both. You’ll create so much goodwill by doing this.

TODO:

Create prominent homepage link: Ruby Compatibility. Show list of updated coding idioms (in both directions) to make it as easy as possible for Rubyist to do Crystal, and vice versa.

Continuing The Discussion

Crystal still has a chance, before going 1.0, to create a much better face to users, to showoff its features and capabilities. If I could decree it, I would advise dedicating a whole month to revamping, updating, and testing a system to automatically generate documentation, as you have for code development.

This isn’t an issue of resources, it’s an issue of priorities. Sidef made it a priority to create good documentation so that potential users (certainly me) would feel comfortable (even inspired) to try it, as it has so many coded examples to start from.

Crystal is a very worthy project, and a very good language, and I want to see it being used much more. I know making the documentation more accurate, visual, and complete, will increase its usage, and thus you’ll receive more external resources and help to continue its development.

If you present Crystal right they will come (and stay)!

2 Likes

There are lot’s of topics covered here!

I want to chime in in some of the things that are said.

  1. During last week we were actually playing around docusaurus, and at Manas we are really liking it. And it covers most of the points wanted in https://github.com/crystal-lang/crystal-book/issues/261
  2. There are some proposals another structure of the crystal-back here and here. I really think we need to cover first time interactions in a better way. Actually there is PR coming on that direction by @ftarulla.
  3. Although helping Ruby users to feel more comfortable with the language is nice. There is no “migrate from ruby” story. And we should be able to express the value of Crystal without comparing to another language. The fact that we share things with Ruby is because we trust/like those decisions. So I would not make the compatibility with ruby a top story.
4 Likes

The issue here isn’t whether you think you need to do it, it’s something you should do because it makes Crystal more comfortable to use to Rubyist. This is about marketing and human psychology, not coding.

This is why many very technical projects fail because their devs don’t appreciate technology is used by humans, and other humans make decisions on it use and control, not them.

This is one problem the Rust devs keep making by refusing to put more things into its stdlib because of an ideological fixation on it being minimalist. Users don’t give a damn about how large a stdlib is, they just want to code their task with the least amount of work/hassle possible.

Don’t you see the potential of the possibility of Basecamp implementing some part of Rails in Crystal because they may not need to change any of their source code to get a 10% - 20% improvement in performance? Performance is a major reason ex Rubyist created Elixir to deal with scaling concurrent tasks.

Please, don’t think about the code, think about how to educate/entice people to use it.

The syntax and some of the core APIs are heavily inspired by Ruby, but Crystal is also heavily informed by people’s experiences with Go, Java, and various other languages. And many of the Crystal APIs inspired by Ruby also exist in other languages.

I’m not even sure Ruby is the largest influence anymore considering how different a typical Ruby program and a typical Crystal program are conceptually. The syntax alone doesn’t make Crystal and Ruby more similar than Java, JavaScript, C, C#, and various other other curly-brace languages.

Then there’s the fact that catering specifically to Rubyists implicitly leaves everyone else out. It implies that Crystal is primarily a language for people who know and love Ruby, when instead it’s made by people who know and love Ruby. That’s an important distinction.

It would also make it harder for Crystal to shake the narrative that it’s “a faster Ruby”. Crystal is very much its own language at this point with so many unique perspectives — similarly to how Ruby wasn’t just another Smalltalk.

I really hope you can see the irony in claiming to come from a perspective of marketing and psychology while rudely shoving your opinion at someone about what they should do.

I have people skills!

2 Likes

Making Crystal more attractive to Rubyist would not be a sign of weakness, it would be an act of Intelligence.

Doc said, man lose weight
Man sought second opinion
Last words on tombstone

Smart with CS degree
Brilliant language, with no docs
List dead software long

Crystal nice language
Ruby unused until Rails
Good tech not enough

As far as I know, Matz liked Perl and wanted to make a better Perl. He also copied the def keyword from Python. Yet I didn’t see anywhere in the docs or tutorials out there migration paths for people coming from those languages.

That said, I agree that docs for all kinds of things would be great:

  1. how to use Crystal if you know Ruby
  2. improving the current docs
  3. introducing a tutorial

The first issue with those 3 points is that we lack time, people and money to do those things. Sure, we can stop everything we are doing right now and start improving the docs, but the language will become stale. And right now the goal is to reach 1.0 first. Once we reach 1.0 there will be less changes to the language and it will be easier to write docs.

Regarding point 1, I recall from another thread that you had trouble translating lambda from Ruby to Crystal. If you go to the Ruby docs about lambda it says it’s just like Proc.new with a few differences. Then if you search Proc in Crystal you find the docs, and they already include examples on how to create them.

Should we make a section in our FAQ saying “if you need to use lambda, do this”? Should we add a section for every possible Ruby feature and method? It’s a bit overkill, we can’t anticipate what you’ll use. However, you can ask those questions in StackOverflow and, with time, it becomes a growing and living documentation site. That’s why StackOverflow is so popular, because they realized having a central place to ask questions and grow docs is better than relying on the core team to write every possible question and answer.

3 Likes

Thanks for raising this issue! I couldn’t agree more that good documentation is the key to success.
And especially thanks for sharing the resources, it’s always great to get good input on that.

I’ve occassionally heard Crystal being praised for it’s good documentation. And in fact, it is quite good in some places. Others not. That’s to be expected though. Especially in stdlib, APIs that have been revisted and polished to a apoint we’re quite certain that’s how we want them to be, are usually quite well documented. Usually not excellent, but fairly good. Then there are other APIs which we’re not entirely sure about or know that we want to change them at some point. Doesn’t make much sense to put effort into documenting them.
I’m not entirely sure about the overall state of the language reference. There’s obviously a lot that needs to be done, but as @asterite said this should happen when we have some guaranteed stability.

It’s great that there are some TODOs listed which we should definitely look into. And in fact, some are already tracked as specific actionable items.

  • The tool we’re using for building the language reference obviously isn’t as important as the content. But still, Gitbook has enough issues that we need to move to a better tool, even if it’s “just” to improve UX (for both readers and writers). There’s already an issue for that at https://github.com/crystal-lang/crystal-book/issues/261 Would be great to get some comments and ideas on that!
  • Accuracy of documentation is probably not so much an issue for the API docs because they are documented inline and we make sure that API changes are reflected in the doc comments.
    But for the language reference this is harder to track because it’s managed separately. I suppose after 1.0 we should look into a more formalised RFC process for proposing changes which should indeed require to write documentation before the implementation.
    Until then, a good way to start would probably to look at the history of merged PR’s with topic:lang tag (there are more tags to keep track off) and check whether the documentation represents the introduced changes. This should be part of the release process (can be started before, of course).
  • We should certainly write more blog posts. A few recent topics that would be great to cover but might have pending changes are exhaustive case (@asterite) and Log (@bcardiff). Improvements for win32 support should defintely be worth a story for 0.35.0 (@oprypin) , maybe the option parser rewrite (@RX14) and I could write one about Path to promote its usage. Unfortunately, this is all time consuming. So no pressure on the people I’ve pinged. It’s just that you usually most familiar with the changes you implemented :smiley_cat:
  • Ruby compatibility has several spects to it. I’m pretty sure we’re pretty confident about the things we do differently from Ruby and won’t introduce aliases like include? just to make porting easier. Crystal is so much a different language with different concept that you can’t just simply change a few things here and there to port it from Ruby code. That’s just not how it can work.
    Porting from Ruby is probably still easier than from other langauges because of shared concepts and ideas. The features of Crystal are typically attractive to Ruby developers, and the many similarities can make it hard to spot the actual differences. So we definitely need to have resources for developers with Ruby background (but we can have those for Python, Golang, Rust etc. as well!). I’m not sure if the wiki pages Crystal for Rubyists and Crystal Shards for Ruby Gems are well known. They’re definitely not very prominently placed and could need some love for bringing them up to date. But they’re already good starting points.
2 Likes

This is the most important thing, because always compare to another language (“We are like xxx but faster!”) is something that can alienate users instead that bring people to the community

Exact!

The only problem with Crystal docs in my point of view is to give a “bookish” structure. Something like Rust Book. Some passages of the documentation are not very structured and perhaps take some concepts for granted.

The docs are already good, they just need more code examples and improved definitions

edit: Which hopefully… will be added over time

Without a set of specific metrics to measure against this is just a subjective “feeling”.
Metrics such as: accuracy, code examples coverage, videos, language translations, etc.

Also, documentation should be produced to satisfy language users, which is different from documentation for language developers.

If there is no time schedule to have something done it’s just a wish, a non-priority.

See SMART goals: Specific, Measurable, Achievable, Relevant, Time-bound

1 Like

One thing that I’ve brought up in the past is just that the documentation generation needs some love. It’s not bad, but it’s pretty minimalist and missing quite a few features that could be beneficial, namely:

  • Customizable backends
  • Theming
  • Standardization of things like examples, property descriptions, etc.
  • Runnable code examples?
  • Testable code examples?

The documentation generator itself also isn’t extremely approachable. It’s basically undocumented, and not very accessible from code. It would be nice to actually have the generator as a separate shard.

It would also be great if we were able to implement documentation example testing. This would go a long way towards keeping docs current. It would require standardizing the way code examples are added to docs though. Something like the @example annotation.

As far as the documentation itself, Crystal is by far not the worst documentation I’ve seen in a language, but it’s far from the best as well. We need to just start going through piece by piece and add documentation for everything that’s missing it. It’s a lot easier to do that after the language is stabilized though. If we had a merge freeze a month or so before the release of v1.0 just to allow the updating of documentation and other similar tasks I feel like we could get most everything taken care of.

Yeah the docs generator needs improvements. But that primarly affects the form of presentation (yes, and usability). But the content is largely independent of that and should be more important for improving.

We can also add improvements to the generator that helps making the content better. But the need for internal refactoring and proper specification is a huge obstacle to that. So currently, the best approach is to focus on improving content with the current tooling capabilities.

The Tails operating system just put out a call for a technical writer.

https://tails.boum.org/jobs/technical_writer/

I’m confused, what does this have to do with Crystal docs?

The notice represents a number of things the Tails project recognizes:

  • their current level of documentation is deficient
  • better documentation is necessary to take the project forward
  • they decided to take the burden off the developers for doing this
  • the best way to do this is to seek skills outside the project to do it
  • the best way to make this happen is to pay for these skills (you get what you pay for)
  • they made it a priority because they put a timeline for getting it done

Creating Documentation is a skillset, just like designing a compiler and writing code.
Paying people who know how to do it is the most efficient/fastest way to get it done.
Good documentation is necessary for the longterm health, growth, and use of any project.

Really writing good docs isn’t that hard, it’s just time consuming