Improve Information Architecture

[dselman]

A top-down review of how we organise the information in the documentation and who it is for.

This is becoming more pressing as we work on the documentation for Cicero v0.20 with the new CiceroMark markup, as well as folding in the documentation for Concerto.

Related issues:
#108
#96
#91

Straw man proposal:
https://docs.google.com/spreadsheets/d/1YaGFm6t0Y__tzdG_N6fUCG5EvjdeiffpB3JMdKR-zA0/edit#gid=0

[gabrielgene]

Hi @dselman
How can I help here?
You want to make the documentation structure the same as the spreadsheet?

The overview section is this?

I can do this ;)

[dselman]

There have been good improvements already. We will discuss and review at the next Tech WG call, Wed 4pm EST. You are welcome to join!

[jeromesimeon]

I really like some of the suggested reorganisations. I have a couple of suggestions though with the following goals:

1. For the "developer in a rush", a section that would get someone started in 15 minutes tops
2. More clearly separate tutorials from technical material
3. Increase the visibility for the key syntax guides: Markup guide, Concerto guide, Ergo guide which are fundamental for anyone who wants to author templates

I've put those ideas into a similarly-shaped spreadsheet here:
https://docs.google.com/spreadsheets/d/1oEKG6T1qZWhSkWO_X3wbm6B3Q56DoCoGrHV-Y489SLs/edit#gid=0

Differences with the previous spreadsheet:

1. Adds a Getting started section
2. Renames/organizes some of the Sections to be either "Legal/tech tutorial" or "developer tutorial"
3. Separates "Template Guides" section (teaches the syntax for text/model/logic) which is distinct from "Reference"

[jeromesimeon]

@dselman @4katie @peterhunn @irmerk Has this been addressed by the latest reorganisation of the documentation, or should we leave this open and do another round?

[4katie]

@jeromesimeon I think it looks pretty good for now, maybe if more feedback comes along we can make more amendments then?

[dselman]

Happy to close. You win this round!

[jeromesimeon]

I'd like to see this as a happy compromise between best and good! Closing this issue.