[RFE] Provide a smoother onramp to initialisation

[pmatulis]

Despite ongoing documentation efforts, there is a sense that the project can benefit from a smoother onramp for the initialisation step so that users can more quickly understand the purpose and the benefits of the starter pack.

Possible solutions:

a) The README can contain solely an overview of the project and a quickstart procedure that gives the user a demo scenario that can be wiped once a proper initialisation is desired. This would necessitate that we go against a previous conscious decision to maintain a monolithic README.

b) A sandbox site that a user can immediately interact with.

Note: If (b) is achievable, we could use a similar strategy for QA purposes.

[ru-fu]

I'm not sure I understand the scenarios 100%. The current setup works out of the box, and a user can start editing the index.rst file with their own content right away. Is that what you mean with (b)?

I feel that the main problem is that RST isn't straight forward, but requires some learning and reading up on. That's what the style guide is for, to make it as easy as possible to get started.

[degville]

Peter and I observed a team using the Starter pack to setup their docs. Things went very well.

But it was also obvious that they needed to do a lot of scanning of the readme, and were often skimming through it for their next steps.

They had a preference for a quick "Getting started" guide that would take them to the rendered content in the browser as quickly as possible, from where they could then hack around to see how things worked without needing too much up-front theory. There was also a suggestion that the rendered content could itself be the next steps. I think this is a good idea.

[ru-fu]

If we start recommending the init script (which I'm totally for), the steps would be:

1. Download the init script.
2. Run the init script.
3. Build the HTML.
4. Go to the docs in the browser and do the configuration as described in the readme.

That's hardly a change to what we currently have, except that we would reduce the "Initialise your repo" step to one set of instructions (possibly with an optional "if you want to do it manually ..." section) and we would explicitly tell them to access the docs after building them.

We could probably even add the instructions ("next, run make html") to the end of the init script and an "access the docs at localhost:8000" to the end of the build ...

[ru-fu]

In the future, we'll recommend using the init script.