Documentation Contributions

Contributing Documentation to the Scala project

There are several ways you can help out with the improvement of Scala documentation. These include:

  • API Documentation in Scaladoc
  • Guides, Overviews, Tutorials, Cheat Sheets and more on the docs.scala-lang.org site
  • Updating scala-lang.org

Please read this page, and the pages linked from this one, fully before contributing documentation. Many of the questions you have will be answered in these resources. If you have a question that isn’t answered, feel free to ask on the scala-internals Google group and then, please, submit a pull request with updated documentation reflecting that answer.

General requirements for documentation submissions include spell-checking all written language, ensuring code samples compile and run correctly, correct grammar, and clean formatting/layout of the documentation.

Thanks

API Documentation (Scaladoc)

The Scala API documentation lives with the scala project source code. There are many ways you can help with improving Scaladoc, including:

  • Log issues for missing scaladoc documentation - Please follow the issue submission process closely to help prevent duplicate issues being created.
  • Claim Scaladoc Issues and Provide Documentation - please claim issues prior to working on a specific scaladoc task to prevent duplication of effort. If you sit on an issue for too long without submitting a pull request, it will revert back to unassigned and you will need to re-claim it.
  • You can also just submit new Scaladoc without creating an issue, but please look to see if there is an issue already submitted for your task and claim it if there is. If not, please post your intention to work on a specific scaladoc task on scala-internals so that people know what you are doing.

The Main Scala Documentation Site

docs.scala-lang.org houses the primary source of written, non-API documentation for Scala. It’s a github project that you can fork and submit pull requests from. It includes:

  • Overviews
  • Tutorials
  • Conversion Guides from Other Languages
  • Cheat Sheets
  • A Glossary
  • The Scala Style Guide
  • The Scala Language Specification
  • SIP (Scala Improvement Process) Proposals and more

Please read contributing to the docs.scala-lang.org site through before embarking on changes. The site uses the Jekyll markdown engine so you will need to follow the instructions to get that running as well.

Updating scala-lang.org

Additional high-level documentation (including documentation on contributing to Scala and related projects) is provided on the main Scala Language site, and is also kept in the scala-lang github project which may be forked to create pull requests.

Please read both the docs.scala-lang.org contribution document and the scala-lang.org github README before embarking on any changes to the Scala language site, as it uses the same Jekyll markdown tool and many of the same conventions as the Scala documentation site.