canonical / pebble

Pebble is a lightweight Linux service manager with layered configuration and an HTTP API.
https://canonical-pebble.readthedocs-hosted.com/
GNU General Public License v3.0
145 stars 54 forks source link

docs: splitting readme into pebble docs with the diataxis method #419

Closed IronCore864 closed 4 months ago

IronCore864 commented 4 months ago

Splitting the README documentation into smaller chunks into the docs folder, using the Diataxis method.

Click here to see the preview..

Major changes:

TODO: The current tutorial (docs/tutorial/getting-started.md) is too long, maybe we need to split it into smaller chunks, some fit into the "how-to" category while others may fit into the "explanations" more.

AnneCYH commented 4 months ago

Hi @IronCore864 , this is a lot clearer, thanks!

2 changes for now:

  1. "How-to guides" index title should be sentence case.
  2. Remove the "Table of contents" from each index page. The no-stacked-headings rule.

I can see the content starting to modularise, which will make it easy to keep each section clean, avoid duplicates, and easy to cross-reference.

I do think some sections should be merged or added.

  1. Get logs + use log forwarding are all related to a single entity for Pebble, "logs", and don't need to be separate either.
  2. Other content that may be 'missing', e.g. related to Files. When i run pebble help, the commands are categorised, but the current README doesn't necessarily address "Info" (e.g. managing your Pebble installation in terms of version, updating to a newer version), or "Files". But this can be done in a separate PR.

Overall I think it's a good start. I only left 1 minor comment about the title for the How-to index page; but other than that I think it's good to go for the first draft.

Thanks!