Improve documentation for Beta release

[conradoplg]

Motivation

For beta release it would be good to improve documentation to make it more clear what is the purpose of Zebra and how to install and run it.

Specifications

Designs

Solution

Closes #2870

Review

Just a draft for now. Feel free to suggest any changes.
Not very confident on the content, just wanted to get it started.

Something I'm not sure about: if we choose to avoid the repetition between README and user guide about setup procedure, should we keep it in the README or in the user guide?

Reviewer Checklist

• Code implements Specs and Designs
• Tests for Expected Behaviour
• Tests for Errors

Follow Up Work

[teor2345]

Something I'm not sure about: if we choose to avoid the repetition between README and user guide about setup procedure, should we keep it in the README or in the user guide?

I have no strong opinions here.

But in general, I think a shorter README is better, as long as it has a brief summary of the setup.

[teor2345]

macOS failed with an unrelated unit test timeout, PR #2895 should fix that timeout.

(This failure is not a blocker for this PR merging.)

[mpguerra]

Great start! Thank you for getting the conversation going on this :)

[conradoplg]

Updated:

• 9a36701: incorporate some of the text from the last newsletter
• 6efde14: organized the README / user docs
  • Moved the detailed instructions to the docs and kept a slightly reduced version in the README
  • Moved "Architecture" entirely to the docs

I think the original commit (4d65495) is too verbose and should be trimmed down a bit (if we actually want to include it)

[mpguerra]

I like these additions to the README, they give a good background. One thing I remember from our usability studies early this year is that people "who know what they are doing" like to get to the "Getting Started" section to start running things straightaway.

I wonder if we can have a short table of contents like list of anchors at the start that jump to:

• About
• Alpha/Beta Release
• Getting Started
• System Requirements
• Current Features
• Known Issues
• Future Work
• etc...

So that experienced users can skip the intro and go directly to the sections they are interested in.

We may not want to have all of the above and just pick and choose the sections we think people are most likely to want to skip down to...

[conradoplg]

I like table of contents! Added in 4670ddd, I've also organized the heading levels to something that I felt made more sense

[oxarbitrage]

Some small spacing issues

[oxarbitrage]

Looks really good. Thanks for the work here.

[dconnolly]

👍