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.
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?Hi Dave,
Yep, I’ve been talking with Daniel Spiewak about that- we’d love to include the style guide in the central repo. You and I should chat more about that- there are a few considerations that’d need to be made for contributed docs.
Regarding the doc comments and the final
*/, you’re right- in Gilles’s original spec, he called for the*/to go on the last line of the doc (not separate). So, officially you’re correct- I’ll update the wiki so we’re all in agreement. Thank youI 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.I can do that too- I agree that many would probably be more comfortable with the
*/on its own line- even Martin generally follows the javadoc convention. So sure, I’ll change the spec, you take care of the style guide. ThanksI 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.
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?
The Djangobook spin on the site was unfortunately lost. Mostly because it’s already too difficult to collect and manage feedback from mailing lists. With Disqus comments as a starting point, we’ve found that having to collect feedback from multiple doc pages in addition to the feedback from all of the mailing lists is simply too difficult for us to incorporate into decisions made during Scala meetings.
Regardless– the result of this blog post was published some six months ago on http://docs.scala-lang.org. It’s an open-source documentation repository containing many different types of documents, from detailed overviews to cheatsheets. The source is available at http://github.com/scala/scala.github.com