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 Contributors mailing list 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.
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 Contributors 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:
- 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.
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.