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 Review by Abigail McCarthy #711

Open
microwavables opened this issue Jan 8, 2024 · 1 comment
Open

Docs Review by Abigail McCarthy #711

microwavables opened this issue Jan 8, 2024 · 1 comment
Labels
carvel accepted This issue should be considered for future work and that the triage process has been completed discussion This issue is not a bug or feature and a conversation is needed to find an appropriate resolution documentation This issue indicates a change to the docs should be considered enhancement This issue is a feature request

Comments

@microwavables
Copy link
Contributor

I've moved the info from the Google doc that @a-mccarthy created into this issue for us to reference and keep track.

Review Date: August 2023

This is a docs review of the carvel.dev website and Github repo. Suggestions and criteria for the review came from the CNCF tech docs assessment guidelines and the google developer style guide

This review is intended to highlight what’s working well on the website and provide suggestions for improving the website's site content, structure, and processes.

Documentation

Information Architecture

  • I think you’ve done a great job of creating content for each project and the flow of content feels good.

Suggestions

  • Missing a “What is Carvel?” page.
    • Aside from the brief note on the home page, there isn’t any content that describes WHAT is Carvel, WHY Carvel was created, WHEN to use Carvel, HOW were the tools created and selected to be a part of Carvel?
    • Is there a video/blog we can pull this information from?
  • Separate the FAQ and contributing/community pages into two sections
    • Create a new section that is “Contributing” or “Community” and move docs that aren’t FAQs there
  • Make all the side navigation the same on each project
    • It feels weird and hard to navigate with the sections each being different. Someone going between the projects might have trouble navigating between the different sections
    • It might help create the idea of unity between the tools in Carvel, if they have more uniform structure in how they are documented or talked about
    • Do users frequently jump from project to project when looking at docs?
  • Change project ordering on Project dropdown to be meaningful
    • It’s not readily apparent why the projects are ordered in the way that they are.
    • Maybe consider doing by alphabetical order
  • Change the Resources page to be labeled something else? https://carvel.dev/resources/
    • Resources always strikes me as a little vague.It frequently ends up as a catch all page for things, but who curates this page? When do things get taken down or added? Can anyone from the community add to this page?

New user content

  • Embedded demos are really great! How easy are those to create?
    • We should also make sure the recordings are accessible, or the page content shows the same thing as the demo for readers who use visual aids
  • The yaml playground is also really nice
    • Do you get a lot of folks using it? Can we put it on more pages or on its own page in the docs?

Suggestions:

  • Create a “Getting started” guide for each project.
    • Many have and “Install” page, but there isn’t always a clearly labeled “START HERE IF YOU ARE NEW” section for users to know how to get started after they install
  • Add a “What’s next?” section to help readers know some related content after installing or getting started guide
  • Use second person, you, instead of “we” or “users”

Content maintainability

  • Release specific docs, yay!
    • Some ideas to help clarify versoning
      • Is there a doc on release processes we can link to?
      • How many release version docs of each tool are kept on the site?
      • How does a user get older docs that are no longer on the website?

Content creation processes

Contributor Documentation

  • You have some good guides on contributing to the project, how to get involved in the community, and where to get in touch with maintainers

Suggestions:

  • Make it clearer on the contributing guide on the website that there are many different repos and the contributing processes apply to all of them
    • Outline what types of things go in the Carvel repo, and what goes into specific tool repositories
  • How are docs issues handled? Is there an active Docs issue backlog?
  • Where are docs issues primarily created? In the carvel repo or in the specific project repo?

Miscellaneous ideas

This is a list of some random things I noticed reading through the docs. They are more on-off clean up issues that might be candidates for good first issues or help wanted issues

Home pages

Questions

  • Some tools have a lot of pages of docs, and some have a smaller number of pages. Is there a tool that you feel is missing some docs?
    • For example, ytt has lots of docs but kbld has a lot less. Is that because ytt is a much larger/more complex tool than kbld, or because there hasn’t been as much time to write kbld docs?
  • Elaborate on what composable means. Many people may know what you mean by this, but it feels like its slipping into “jargin/overused” territory.
@renuy renuy added enhancement This issue is a feature request discussion This issue is not a bug or feature and a conversation is needed to find an appropriate resolution documentation This issue indicates a change to the docs should be considered carvel accepted This issue should be considered for future work and that the triage process has been completed and removed carvel-triage labels Jan 9, 2024
@a-mccarthy
Copy link
Contributor

Some of this work has been broken out into #744 and sub-issues linked there. This issue covers a large scope of work and acts more like an epic. Each topic should be broken out into its own issue to further discuss and split up the work.

If you are interested in working on a piece of the work described in this issue, please file a new issue or look for an already created sub-issue to give your feedback. If you have any questions, please reach out to the carvel community!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
carvel accepted This issue should be considered for future work and that the triage process has been completed discussion This issue is not a bug or feature and a conversation is needed to find an appropriate resolution documentation This issue indicates a change to the docs should be considered enhancement This issue is a feature request
Projects
Status: No status
Development

No branches or pull requests

3 participants