Improving the State of Scala Documentation

As many of those who attended Scalathon, or have been following the scala-language mailing list already know, my name is Heather Miller- I’m a PhD student at EPFL, and now the Scala “Documentation Czar.”

So, great, we can all agree that the state of documentation needs to improve. But what kind of documentation-related tasks will be on the radar? I’ll be focusing my (part-time) energy on two aspects of Scala documentation; (a) spackling up the holes in the current API, and (b) providing a one-stop home for high-level documentation like programming guides or overviews.

Contributors wanted!

Though, I can’t do this all on my own. So, I’m currently working on ways to facilitate the task of contributing to all forms of Scala official documentation. Interested in helping? In the near future, we’ll be looking for contributions on two fronts.

#1: API Documentation

Pending the Scala project’s move to github (thanks Josh!), we’ll be encouraging contributions to the official Scala API via github pull-requests. As soon as the move is completed, contributing will become a lot simpler, especially if you’re familiar with github and have a scala fork. For a step-by-step how-to, and suggestions on places in the API to begin contributing to, check the doc spree wiki page.

So far, efforts like the documentation spree at Scalathon have already been tremendously successful (thanks Yuvi!), garnering some 35 contributors, and resulting in improvements to something like 16 areas of the API, which are already visible in the nightly API. And what’s even better- Iain McGinniss, a Scalathon doc spreer has even stepped up to organize monthly doc sprees, for anyone interested in participating, online for 24-hour periods. So, if there’s some stumbling block you’ve hit along the road, which required you to go on what you feel is rougher-than-usual route to understanding a concept you believe should be better elaborated upon in the API, here’s a fun and friendly chance to help others who might bump their head in the same place you have. It’s a way to make an immediate and meaningful contribution to the Scala project, and it begs contributors.

#2: High-level Documentation

It might come as a surprise to a lot of people, but the answers to many questions asked on the mailing lists, or Stack Overflow, can actually be found in detailed documents produced by the Scala team- many of which Martin has written himself. These informational gems are curiously tucked away in obscure locations deep within scala-lang.org, in all kinds of formats- often PDF. What’s more- there exists countless other quality and definitive docs produced by the community.

We’re currently working on a solution which aims to make it easier to find and use these documents- those produced both from within the team, and user-contributed, by organizing them all in one central location.

From the outside, what we’re working will feel similar to DjangoBook in its commenting functionality. From the perspective of those who’d like to contribute, we’re currently building on top of git, so new documents and revisions can be submitted via github pull-requests.

We’re aiming to keep documentation living in the central doc repo on scala-lang.org up-to-date, definitive, and branded “official.” So we’ll evaluate contributions from that point-of-view. Whether you have something you’ve already written that you think might be perfect to be included in the scala-lang.org doc repo, or you’re thinking about writing something- if you’re interested in contributing to this breed of Scala documentation, please contact me! (in the meantime, while we build and organize.)

More details on this facet of documentation forthcoming, as development continues.


7 Comments to Improving the State of Scala Documentation

  1. July 29, 2011 at 9:56 am | Permalink

    This is awesome. I maintain the unofficial scala style guide and, after contributing several doc updates, I added a scaladoc style guide, linked here: http://davetron5000.github.com/scala-style/scaladoc/index.html.

    Feel free to link to it, copy it, or comment on it.

    One question: the scaladoc wiki page says to use the style I have in the guide, which is that the final */ goes on the same line as the last line of doc, not on a separate line (which is actually what most scala code does and what your example shows). Is the java-style method now preferred?

  2. July 29, 2011 at 12:04 pm | Permalink

    I think most of the known universe would prefer the trailing */ to be on its own line; other than being what every Java developer coming to Scala will do, it also makes the docs more maintainable by not having to move around the */. If you change the original spec, I’ll update the style guide.

  3. Carlton's Gravatar Carlton
    September 19, 2011 at 4:25 pm | Permalink

    I am not trying to be orthogonal. Honest.
    Just sharing some of my thoughts because …
    Wouldn’t it be great if Scala docs:
    1 – could generate html, pdf and epub output
    2 – allow the above output to be customized (i.e. templates)
    3 – could document high level concepts (like a book)
    4 – could document api’s and test cases
    5 – highlight short code segments

    This is already done via Sphinx, pygments, jinja and docutils for python.
    A video showing how this all works together is at
    http://showmedo.com/videotutorials/video?name=2910020&fromSeriesID=291

    It seems all the hard work has been done and
    maybe scala doc can just adapt those tool for scala, copy from them, or
    just re-implement the whole thing in scala.

    Thanks for your time.

  4. jpe's Gravatar jpe
    March 25, 2012 at 1:54 am | Permalink

    Is what you are working on, that piece which is similar to Djangobook, a public open-source project that can be looked at and constructively commented before it is being released and used? What is the status of this project nearly a year after your blog post?

Leave a Reply

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>