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

Add a more detailed table of contents to the user manual #1340

Merged
merged 17 commits into from
Dec 9, 2023
Merged

Conversation

csasarak
Copy link
Contributor

@csasarak csasarak commented Dec 7, 2023

Overview

Our current ToC is pretty minimal. While it's generally possible to find information through it, it is difficult to know exactly where to go. In particular, it's hard to use it to know everything the CLI is capable of. This PR adds a more comprehensive ToC to the user manual.

The new ToC's audience is for everyone but I made it with a novice user looking for more information in mind. As a result, I made some section headings different than they are in the documents they link to in order to make them friendlier for novice users. For example, instead of a ToC link to "Referenced Dependencies" I use "Deps from a Known Package Manager (Referenced Dependencies)" under the Manual Dependencies section heading.

The overall goal of this is to empower users to figure out how to solve more issues themselves as well as ask more sophisticated questions about the CLI's functionality.

I've avoided editing the docs the ToC links to as much as I can, but a second pass at this might involve restructuring some of our documentation.

Additionally, I didn't link to every single section heading in every document. I mainly thought about how likely a user would be to want to jump to a given heading when choosing. This is subjective and advice would be welcome.

Link to the User Manual.

Acceptance criteria

  1. This ToC makes it at least marginally easier than the current one to find relevant information in our documentation.
  2. This ToC gives a good overview of what it's possible to know about using the CLI.

Testing plan

There's not really a good way to test this. Automated tests verify that the links work but whether it's actually a good thing is subjective.

Risks

Some ToC links link to sections with a different name. I did this to make navigating easier for a user without much context in the CLI but I can also see how it might be confusing.

I only linked to some of the experimental functionality because my understanding is that some of it we'd rather users not use. I'd like guidance if anyone things something should be added or removed.

This ToC will rely on some ongoing maintenance on the team's part. I've added a checkmark to the PR template to help remind folks to update the ToC.

Checklist

  • I added tests for this PR's change (or explained in the PR description why tests don't make sense).
  • If this PR introduced a user-visible change, I added documentation into docs/.
  • If this change is externally visible, I updated Changelog.md. If this PR did not mark a release, I added my changes into an # Unreleased section at the top.
  • If I made changes to .fossa.yml or fossa-deps.{json.yml}, I updated docs/references/files/*.schema.json AND I have updated example files used by fossa init command. You may also need to update these if you have added/removed new dependency type (e.g. pip) or analysis target type (e.g. poetry).
  • If I made changes to a subcommand's options, I updated docs/references/subcommands/<subcommand>.md.

@csasarak csasarak marked this pull request as ready for review December 7, 2023 22:55
@csasarak csasarak requested a review from a team as a code owner December 7, 2023 22:55
@csasarak csasarak requested a review from meghfossa December 7, 2023 22:55
Copy link
Contributor

@meghfossa meghfossa left a comment

Choose a reason for hiding this comment

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

🚀

@csasarak csasarak enabled auto-merge (squash) December 9, 2023 00:39
@csasarak csasarak merged commit 5c21581 into master Dec 9, 2023
17 checks passed
@csasarak csasarak deleted the docs-toc branch December 9, 2023 01:13
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.

2 participants