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.
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.