Importance of Documentation

Chat / Discussions
,
1

I am preparing a meetup Lightning talk on Documentation and the importance of it. I love that in the Elixir docs is states “Elixir treats documentation as a first-class citizen”. I love this but why do we? Does the importance come from bad experience and this is our revenge? (This is not my view but just sparking discussion)

I would love your insight on the why and how would you explain this to someone first coming into this language.

3 Likes
2

In my opinion, documentation is a requirement for a welcoming community. Sure, you don’t really need documentation if you’re motivated to learn the tech. But good documentation lowers the effort barrier and sends a signal that the community cares about newcomers.

3 Likes
3

That’s a good point! By documenting you are inviting people to learn. I like that! Thanks!

1 Like
4
  1. The learning point that @yawaramin already mentioned.
  2. Documentation is the only tool we have to convey important information to the user of our interfaces. In many languages, the concepts of ‘Documentation’ and ‘Commenting’ are conflated, but they are different:
  • Comments are something you write in your code to help you and future maintainers understand why you made a certain implementation choice (like picking a less aesthetically pleasing solution because the performance difference mattered here, or make a note that yes, this line is required because otherwise a race-condition would happen in situation X, etc.). Side note: Comments should not tell you what happens (because, hopefully, the code itself already does this).
  • Documentation, on the other hand, is for people using your code, who need to know the rules your code expects of them. This is even more important in a weakly-typed environment than a strongly typed one, because there are less ways to enforce rules on the end user (to ‘make invalid states impossible’) so the only tool we still have is communication between humans.

The nice thing about making documentation first-class (rather than having documentation ‘tacked on’), is that it is a lot easier for people to find and use it! I find myself using iex's h helper very often, because it is so much quicker than browsing on the internet to look for the documentation of packages/modules that I already have installed on my local system.

3 Likes
5

That was honestly one of the things that made an excellent first impression to me ~2.5 years ago with Elixir.

People on Reddit and HN have called Elixir “a language with good marketing” many times and I find myself in agreement with them… although I think the community should definitely go next-level and prepare several topical Wiki-like posts here in ElixirForum; it’s a natural next step IMO (this post is an excellent example of what I have in mind: HTTP client libraries and wrappers).

Elixir has very no-BS noob experience and this definitely won me over as the jaded C / C++ / Java / PHP / Javascript / Ruby programmer that I was back then.

(Anti-example: deployment. I found Distillery really quick to start with but there’s so many manual steps to do that I have to wonder why are there no wrappers or generators yet. Hell, even if they require 20 CLI parameters I’ll still take it, deployment shouldn’t be such a delicate and brittle job).

So to answer @emeidell – documentation is important because there’s very good tooling that can be built around it (ex_doc; seamlessly building documentation is extremely important for wide adoption, including in corporations) and because it’s a very good marketing tool to show initiating programmers that the language is community-friendly.

3 Likes