[Docs] Structure Sage Monorepo docs

[tschaffter]

What product(s) is this documentation issue for?

Sage Monorepo

Documentation issue

• [ ] Reporting a typo
• [ ] Reporting a documentation bug
• [ ] Documentation improvement
• [ ] Documentation feedback

Description

We now have a solution to render markdown files so that they are displayed on GitHub pages.

This solution requires us to structure the documentation in a way that is intuitive to the users of the doc.

The goal of this ticket is to come up with an initial structure, potentially with placeholder pages and sections, that we can then fill in. In particular, this work should results in clear guidelines on how to write new documentation content, e.g. how to format links, where to place markdown files, etc.

Is there a specific documentation page you are reporting?

No response

Anything else?

There are three places that may include relevant documentation that we may want to include in the doc site:

• Workspace-level README
• Project-level READMEs
• Pages in the docs/ folder

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[vpchung]

First proposed change: categories

I want to first focus on the different categories the docs should have. We currently have the following:

If I were to put myself in someone else's shoes, these categories may not be as straightforward to navigate through. Taking inspiration from Angular, I propose we have the following instead:

where:

• Home - showcases the main features of the sage-monorepo and what projects it currently supports
• Getting Started - introduces the main technologies of the monorepo (Angular, Nx, Devcontainer) and how one can set up locally or on a remote host
• Developers Guide - the bulk of the docs; where one can find out to monitor the stack, collect logs, update dependencies, common issues and how to debug, etc. This category can then be split into project-level guides, e.g.:
  • OC: add a new Angular library, add a new Angular component, edit styles/themes, add tests, etc.
  • schematic: add a new API, etc.
  • iAtlas: ...
  • Agora: ...
• Reference - cheat sheets
• Updates and Releases - changelog, release notes, etc.
• Contributors Guide: walks through how one can contribute to the monorepo (bug report, feature request, adding a feature, updating the docs, etc)

In your opinion, would this new structure be more intuitive? @tschaffter @rrchai @mdsage1

[tschaffter]

This is a great start! Here are some suggestions:

• Developers Guide: I would suggest to structure it by programming languages, framework and technologies rather than projects. This structure would better support the creation of standard and the reuse of existing docs.

• Contributing Guide: Could this section be included as part of the Developers Guide?

• Products: Section to introduce the different products developed in the monorepo (OpenChallenges, Schematic, etc.) + group the documentation of their different components (project-level README)?

• Reference: The term may be a bit too vague. Maybe Resources? (better?) What else could fall in this category in the short term? Videos? The Code Quality dashboard?

• Updates and Releases: Maybe split the two to be more specific? While releases information would typically be captured by GitHub releases, this seems difficult to provide project-specific release information in the context of a monorepo. So I'm all in for placing releases information in the docs. Updates sounds a bit vague. What about "What's New?" or "Feed"?

[vpchung]

"Reference" is a common category in other docs, at least the ones I've come across.

It's generally where one could quickly find all the available commands to run, or a list of all of the available class libraries, object models, etc. I think for our purpose, "Reference" could be a good place to put our "cheat sheets".

EDIT: Looks like "Reference" and "API reference" are the names commonly used. But I don't think "API reference" is what we would want?

[vpchung]

While releases information would typically be captured by GitHub releases, this seems difficult to provide project-specific release information in the context of a monorepo.

You're right - I'll go ahead and remove that!

Contributing Guide: Could this section be included as part of the Developers Guide?

Updates sounds a bit vague. What about "What's New?" or "Feed"?

Hm, what do you think about removing these as categories and using them as sections instead? Perhaps for the Home category? For example:

[tschaffter]

Added to Sprint 24.2