Documentation is underrated

[Nahida]

While passionate discussions and dedicated development fuel new features in the Scala world, documentation often receives much less attention.

Yet, in its current state, investing in thorough, user-friendly documentation could offer a significantly higher return than releasing yet another awesome feature (particularly if it’s poorly documented and/or half-baked). After all, Scala already boasts an impressive feature set, while its documentation leaves much to be desired.

Perhaps a new principle is worth considering: no feature release without comprehensive, up-to-date documentation and practical examples (the same rule applying to feature updates). As the saying goes, if a new feature drops in the Scala forest with no documentation to guide users, did it ever truly arrive?

[alvae]

You bring an important point and I think you’re right. I also personally found Scala’s documentation difficult to navigate and even lacking in some places.

Note, however, that writing a “comprehensive, up-to-date documentation [with] practical examples” is a colossal job. So I doubt it could ever be something we can do while freezing development on everything else. Instead, it is much more likely that we can make parallel progress with a working group of motivated people like you.

I think that a good way to start improving our documentation would be to put together a list of specific grievances and attach actionable items to them and/or point to examples of other projects having addressed the issue better. Would you be willing this lead this effort by any chance?

[Nahida]

Thank you, @alvae!

It is a colossal job. For each new feature, however, I do not believe it is quite as much work as developing the feature itself. My main point is that the documentation should be developed hand-in-hand with new features, rather than as an afterthought. (My previous main point was that, in the current state of affairs, any effort on documentation would have a higher ROI than any effort on feature development.)

Currently, Scala has a lot of documentation debt, and it might take a month or two of freezing all other development to significantly reduce it. I don’t personally think this would be a bad thing. But I was mostly thinking about how to change development in the future so as to avoid a further growth of that debt.

I also think the production of new documentation has to be spearheaded by the core feature developers, as the best documentation is almost an extension of the code itself. Similarly to test-driven development, or security from the ground up, I recommend more documentation-driven development.

While such documentation-driven development might sound like a lot more work initially, it can actually also help feature development, making the net added effort very much worthwhile, not entirely unlike typeful development.

Regarding the improvement of existing documentation, I do not think I am in a position to lead any such effort. The main reason being that I am a nobody, so the community would not accept me as a leader, and rightfully so. Another reason is that I have very little bandwidth for any project, really.

Making a list of grievances should really be a group effort; I think everyone can pitch in. Some have already been reported as issues on GitHub and in other places, like stackoverflow and Scala Users. Even some of the issues being reported about the Scala compiler actually stem from a lack of documentation, and can help prioritize documentation improvements.

[som-snytt]

I would cast a dissenting vote.

Although documentation has value, it’s very difficult to determine which documentation and where.

I agree that the issue tracker (any issue tracker) is the right place to drive the process. That requires people willing to take the time to a) lodge tickets and b) fix them.

Although I have spent time improving API docs, and I felt that I learned something that day which I later mostly forgot, I have also wondered whether it was a worthwhile pursuit. It would be nice if Scaladoc counted page views, as blogs used to. Or a tip jar for contributors, that would be great.

Someone just asked a question that is in the FAQ. Is it buried in the FAQ? Why isn’t the initialism, RTFFAQ? My point is that just structuring doc is very difficult. Is there an initialism for DOX, the doc experience? I’m not an expert, though I have years of experience complaining about DOX.

There are “books” and “tutorials” on the doc site, as well as the Scala 3 reference, which has seen tickets written and PRs submitted against it. There are also third parties on youtube willing to explain stuff.

Perhaps the rule should be: Add no feature that makes me read documentation.

Or, as with -no-indent, which is favored by some, make it trivial to turn off.

My limited experience is that you can make a lot of progress in Scala 3 by ignoring features. Also ignore whatever Odersky was talking about in the last keynote about what will change our coding lives in five years. I know it’s difficult. The doc site needs a button upfront for NO FOMO, which hides all information about the latest features.

Also the compiler needs -no-fomo, so I don’t accidentally use something I’d have to look up in the manual. Or worse, something I’d have to help document.

[bjornregnell]

Our ability to make use-case-agnostic documentation is overrated.

[som-snytt]

Actually, I stopped what I was doing to document something about migrating to Scala 3.

[alvae]

@som-snytt

Although documentation has value, it’s very difficult to determine which documentation and where.

Very true. That is why I think a documentation improvement effort requires first and foremost input from the community to better understand what exactly has to be done. Otherwise “improving a documentation” is a goal as vague as “making a text clearer”.

That is not unlike reporting a bug: we have to explain what we’re doing, isolate a reproducer for the issue, describe the expected outcome, and show how it differs from the obtained result. Without that it is very difficult to know what we have to fix and evaluate whether or not we fixed it later on.

Here, I would say that the reproducers are descriptions of the moments we felt loss during our interactions with the documentation because we were trying to achieve X but didn’t know how to use Y. A good start to identify them would be to answer these questions:

• What kind of experience am I expecting?
• How does the current documentation not meet these expectations?
• What did I see in other projects that addressed the issue better?

If we’re not willing to take the time to answer these questions (among others) thoroughly, then I think we’re not in a position to demand better documentation.

@som-snytt

My limited experience is that you can make a lot of progress in Scala 3 by ignoring features. Also ignore whatever Odersky was talking about in the last keynote about what will change our coding lives in five years.

I wholeheartedly disagree that one should stay away from new features. Adoption is the only way to surface real use cases, which then can serve to build solid documentation. If a feature has no user, then it is unlikely to be easily documentable.

That isn’t FOMO. It is healthy to not throw every possible “cool” trick at a problem, but it is also counterproductive to stay away from better tools, even if they may seem scary at first glance.

If Martin is right and in five years everyone does indeed use X, then that is precisely because of adoption that X will feel natural and not worthy of pages and pages of documentation. We can certainly look at all “obvious” features of modern PLs today and find a point in time where they were unfamiliar and “poorly” documented. Should we have stayed away from them then, we wouldn’t be comfortable with them now.

@som-snytt

Also the compiler needs -no-fomo, so I don’t accidentally use something I’d have to look up in the manual. Or worse, something I’d have to help document.

I find that to be a strange position to hold in a project that is in large part carried out by an open source community. The scouting rule should apply to documentation just as it applies to code.

[Stephane]

Here are some documentation pages I think are missing:

• Higher-kinded types

  • Where they are allowed and disallowed (union types, match types, <:<, … )
  • How they have to be written out, depending on the context

• Scala 3 compiler options/flags

• sealed, final

• isInstanceOf

• Wildcards (?, *, _ (soon-to-be deprecated))

• Access modifiers (private, protected)

• Advanced feature imports (like import scala.language.implicitConversions)

• Conditions (assert, require, …)

• Mirrors

I’m sure I’m missing lots. Simply going through Scala concepts and googling them is a good way to find more that are missing dedicated documentation pages.

[som-snytt]

I’m pleased to see that Scala is now self-documenting!

I don’t disagree with your reply, except to the degree I was not entirely joking at the end of my post. Some people don’t wish, or rather, don’t deserve, to live on the bleeding edge.

Sometimes when I’m reading a discussion or debate, I think, that sounds very interesting, I wonder what they are talking about. If they are using math symbols, that is especially attractive to me, it’s like seeing some text in a foreign language and you immediately want to know how to say, “Un café americano, s’il vous plaît.”

The reason I didn’t get to the store this morning was that I was reading old topics on the “contributors” forum. I enjoyed reading everyone’s ideas, proposals, and counter-proposals. If reading old PRs is like archaeology, the forum is like opening a box of old letters you found in the attic. My favorite moment was when everyone from the team chimed in to say what a terrible idea “if-then” syntax is and how significant indentation is even worse. Dr. O, who is usually Dr. No, decorously did not attend the SIP meeting that voted down decluttered syntax, already knowing that Dotty would have it anyway. I visited the sips list to see what became of default args that are a function of args in the same param list. I enjoyed this exciting dynamism from the comfort of my armchair, so to speak, that is, from my inexpensive desk chair.

My hope for 2024 is to have a fork of Scala that includes everything ever proposed on the forum, which would be like the everything bagel from “Everything Everywhere All at Once”, but for Scala features. Private method params were proposed twice. I think there should be a rule that after a second proposal, it’s automatically promoted to SIP status. I also think the field needs more puns on proposal as in wedding proposal and proposition as in pick-up line. For example, instead of starting out as proposals, which is rude and presumptuous, SIPs should begin as propositions and evolve into proposals over time, after a seemly period of courtship.

The beauty of Scala-bagel is that all its features are already documented on the forum. One may say, documented at length!

If anyone is interested in presenting at our inaugural conference, a call for papers is forthcoming for “Scala-by-the-Bagel”.

It’s an exciting time to be a Scala developer and documentarian!

@alvae

I find that to be a strange position

I’m not a stranger to strange positions.

@alvae

a strange position to hold

But I am practicing yoga in the New Year, which may assist me in this regard.