Meta: Improve sbt 1.0 documentation

[jvican]

This is a meta ticket describing the problems I find in the sbt documentation and proposing some solutions to address them.

I see several problems with the current status quo:

1. User documentation assumes previous sbt knowledge, or at least some familiarity. I miss a short, opinionated hands-on sbt guide.
2. Sbt internals (for contributors and plugin authors) are poorly documented.
3. Documentation is not easily accessible -- we need an open browser and several clicks to get to the page we're interested in. There's no search box in the website. This takes time and get people unfocused.
4. Docs of different sbt releases confuse users.
5. help is not that helpful -- descriptions are too short and sometimes imprecise.

I think all these can be addressed one way or another. These are my ideas:

1. Create a hands-on sbt guide (I may be doing this on my free time).
2. Use Scaladoc for public APIs. Try to document the most important internals, especially the tricky parts (thing that I've been doing in my latest PRs, in librarymanagement, zinc and sbt/sbt).
3. Improve help and make it accessible and browsable from the sbt shell.
4. Remove docs for 0.12.x.

[muuki88]

@jvican thanks for this ticket 😍 and the well formed ideas on how to improve SBTs documentation​.

For 1) I have started a gitbook SBT Getting Started when I was teaching SBT to students.
It's very rough, there are still check boxes and a lot of spelling and grammar mistakes. However it gives an initial structure and pictures SBT from the clean conceptual perspective.

I'll yet have to add it to a git repo so collaboration is possible. Would you be interested to join on this project?

[jvican]

That is a great initiative @muuki88 😄 Hope you continue it!

The Scala Center is not going to get involved into documentation for now (there is an advisory board proposal regarding this here, but the decision to accept it has been put off for three months). If that gets accepted, I'll look into ways of collaborating, your work in that book is great.

In the meanwhile, if you decide to help us on any of the aforementioned points, I'm more than happy to help you and review your changes. This is a part where community input is crucial. If this sounds boring, just let me know, I can offer you more interesting tickets 😄.

Hope to see you around more often!

[akauppi]

The Akka documentation having a pretty well functioning search these days seems to have raised my expectation levels. Not having search in sbt simply made me quit my visit to the docs, today.

I was trying to find ProjectRef mention on sbt 1.1.0.

How difficult would it be to align sbt documentation with Scala / Akka, experience-wise?