-
Notifications
You must be signed in to change notification settings - Fork 176
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
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Still needs to integration subcommand info.
This reverts commit 73021ab.
meghfossa
approved these changes
Dec 8, 2023
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚀
The goal here is to not generally promote these features.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
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
docs/
.Changelog.md
. If this PR did not mark a release, I added my changes into an# Unreleased
section at the top..fossa.yml
orfossa-deps.{json.yml}
, I updateddocs/references/files/*.schema.json
AND I have updated example files used byfossa 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
).docs/references/subcommands/<subcommand>.md
.