Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: make landing pages more informative #524

Merged
merged 11 commits into from
Nov 27, 2024
Merged

Conversation

dwilding
Copy link
Contributor

The purpose of this PR is to use a consistent style for the three landing pages How-to guides, Explanation, and Reference. How-to guides already has the style we want, so I'm using the same style for Explanation and Reference.

Summary of changes:

  • How-to guides - Adjusted some wording for readability and consistency of language
  • Explanation - Moved General model to the top of the TOC; split the landing page into sections with brief summaries
  • Reference - Applied a logical order to the TOC; split the landing page into sections with brief summaries

Copy link
Contributor

@benhoyt benhoyt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is very good -- just requesting a few nit comments/changes.

In addition, I think we should discuss the ToC order. I think the "natural" or "logical" order is good in the main document, but (especially as things get longer) alphabetical order would be better for scanning/finding things in the ToC on the left. But let's discuss at/after daily.

docs/how-to/index.md Outdated Show resolved Hide resolved
docs/how-to/index.md Outdated Show resolved Hide resolved
docs/reference/index.md Outdated Show resolved Hide resolved
docs/reference/index.md Outdated Show resolved Hide resolved
@dwilding
Copy link
Contributor Author

Thanks @benhoyt! I've included your suggestions in dwilding@e90e04e

Let's discuss the TOC approach today

Copy link
Contributor

@benhoyt benhoyt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, thanks. Feel free to merge as is and figure out the ToC ordering in a separate PR, or include that in this one -- doesn't matter to me either way.

@dwilding
Copy link
Contributor Author

@benhoyt, @IronCore864 I've reorganized the links after our discussion. Changes in 261e6da:

  • Links under Reference are now listed alphabetically in the nav sidebar
  • On the Reference page, I've bumped a few sections to the top, for a more logical reading order. And I feel that grouping auto-restart & health checks together makes for a better explanation
  • Minor adjustments to a couple of link titles:
    • Use Pebble in containers --> Pebble in containers
    • CLI Commands --> CLI commands
  • Added comments in the source to explain how Reference is set up

Let me know if you think anything should be changed!

@dwilding dwilding merged commit 2b5f306 into canonical:master Nov 27, 2024
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants