Docs Review by Abigail McCarthy

[microwavables]

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

• https://developers.google.com/style
• https://github.com/cncf/techdocs/blob/main/assessments/criteria.md

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”
  • More details: https://developers.google.com/style/person
  • For example: https://carvel.dev/kapp-controller/docs/v0.46.0/

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

• Make documentation contributing information easier to find
  • Your contributing guide doesn’t mention docs: https://carvel.dev/shared/docs/latest/contributing/

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

• https://carvel.dev/
  • Experimental tools
    • What does experimental mean to Carvel? How do I learn more information about these tools?
    • Move to below install or have in a separate page, it kinda looks like the install instructions are for installing the experimental tools
• https://carvel.dev/kapp-controller/
  • This is the only home page that is different. It’s missing the Features and basic usage sections
  • Reuse the words in the demo video for the example https://carvel.dev/kapp-controller/. Move the demo up high so folks can see/watch that, then provide the code snippets for them to follow along/do it themselves.
• The “Shared Docs” in the projects drop down seems vague and out of place,
  • Maybe just label it “Contributing”
  • Or add a Contributing section to each side nav
• In the kapp-docs you mention the “core carvel design principles” Is there a page we can link to that describes what those are?
  • https://carvel.dev/kapp-controller/docs/v0.46.0/
• Use second person, you, instead of “we” or “users”
  • More details: https://developers.google.com/style/person
  • For example: https://carvel.dev/kapp-controller/docs/v0.46.0/
• Update Note formatting to be more eye catching
• Page title suggestions:
  • Remove Tutorial from page titles
    • https://carvel.dev/kapp-controller/docs/v0.46.0/packaging-tutorial/
  • Make sure page titles and side nav links match
    • https://carvel.dev/kapp-controller/docs/v0.46.0/air-gapped-workflow/
• Remove TCE information
  • https://carvel.dev/kapp-controller/docs/v0.46.0/oss-packages/
• Code blocks have different formatting in different project docs
  • https://carvel.dev/kapp/docs/v0.58.x/install/ has black code blocks
  • https://carvel.dev/ytt/docs/v0.44.0/how-it-works/ has gray code blocks

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.

[a-mccarthy]

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!