0003-krator.md

cSpell:ignore
Krator celestehorgan CODEOWNERS

Krator Docs assessment

Introduction

This is an assessment of your project documentation and website (if present), prepared for you and your project by the CNCF techdocs team.

This document aims to:

• Measure existing documentation quality against the CNCF’s standards
• Recommend specific and general improvements
• Provide examples of great documentation as reference
• Identify key areas which will net the largest improvement if addressed

Since the Krator documentation site is just getting started, we'll have to create or significantly develop the current content. This assessment provides a starting point for articulating current state and ideas for the future.

How this document works

The assessment is divided into three sections:

• Project documentation: for end users of the project; aimed at people who intend to use it
• Contributor documentation: for new and existing contributors to the project
• Website: branding, website structure, and maintainability

Within each section you receive a rating on different criteria. The full definition of each criteria is defined in Criteria. We recommend reading each criterion’s definition.

Project documentation

Criteria	1	2	3	4	5
Information architecture	✅
New user content	✅
Content maintainability	✅
Content creation processes	✅

Criteria:

• 1 = (Is not present or requires significant work)
• 3 = (is present, but needs work)
• 5 = (is executed extremely well or no improvement required)

Comments

• Information Architecture:

  • Documentation is currently in several locations and will need to be brought into one repo. The current resources are:
    • The project README
    • Introduction to Krator Blog Post
    • A Fistful of States: More State Machine Patterns in Rust
    • Crate Krator API Documentation. This is a substantial part of the current documentation and could be incorporated into the main body (site/repo) of the documentation. This is already a great resource for users, but if we transport it to a documentation repo, it will take some work if it's not already in markdown. Is there a way extract/download these guides quickly? Another important consideration is that because the API documentation is auto-generated as a part of the Rust Crate, documenting these features is convenient for the developers, however, it is more challenging for non-developer users to contribute to the documentation. We recommend that the Krator team determine which path is best in the long term. If we choose to pull the API documentation into the docs repo, there's more up front work, however, the benefit is more potential community engagement.
    • GitHub Documentation. The Community guides teach contributing and development.
      • The Developer Guide covers prerequisites and building, which would make a good introductory or Getting Started entry point.
      • The Release Checklist appears aimed at developers of Krator, as opposed to first-time users. This should ideally be separated from the entry point.

• New user content:

  • We'll need to create a clear entry point for the new user. Some of this info could be taken from the Developer Guide and includes prerequisite knowledge, configuration, and a brief step-by-step guide on adding Krator to your project.

• Content maintainability:

  • Since we'll be creating a site, search doesn't apply yet (though will be part of the basic site).
  • Using Hugo will add the benefit of localization support.

• Content creation processes:
  • The following are ideas to consider going forward with a docs repo. As a content creator:
    • If I write documentation, who verifies that it's technically accurate?
    • If I'm not a native english speaker, who can I ask for help with grammar and language review?
    • If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment?
    • As a developer user, how can I ensure that content is accurate and up to date? Are alpha and beta features flagged? What happens when content (+ functionality) gets deprecated or changed in a major way?
    • Who reviews documentation PRs?

Recommendations

• Information Architecture: The main task with information architecture is conceptualization and development as the documents are currently in different places. The following areas would establish a foundation:
  • About Krator: Give a high-level view of Krator and what it solves. Most common use case(s)
  • A Quickstart or Getting Started: Having an obvious starting point as a top-level section or doc gives new visitors a sense of context. I recommend creating a Getting Started/Quickstart.
  • Tutorials
    • Setting up Krator
    • Configuring your project to use Krator
  • Tasks: I recommend a section with step-by-step instructions on how to accomplish the most common tasks in Krator. For example, if you have five most common tasks, you could have a document for each. Suggestions include:
    • Using built-in operators
    • Creating your own operators with Krator
    • Are there other common tasks? If so, they should go here.
  • Best practices
  • Troubleshooting
    • Troubleshooting
    • Error Reference A table with explanations and resolution steps would suffice
  • Contributing to Krator
    • Cutting releases (This is existing documentation)
    • Contributing: Include information on submitting issues and instructions with links on contributing to the code base and to the documentation.
  • API Documentation: If you choose to bring this into the main documentation repo, the copy will need to be ported. Is the content available in markdown already? If not, it will need to be converted.

Contributor documentation

Criteria	1 = (Is not present or requires significant work)	2	3 = (is present, but needs work)	4	5 = (is executed extremely well or no improvement required)
Communication methods documented	✅
Beginner friendly issue backlog	✅
“New contributor” getting started content	✅
Project governance documentation	✅

Comments and recommendations

Communication methods will need to be determined and added to CONTRIBUTING.md.

While there is an issue backlog, there aren't any issues with a good first issue label. As an invitation to new contributors, consider filing issues that are easy to remedy, labeling them accordingly, posting them on social media, and being available to help contributors through the process.

There is a brief mention of the PR review process in CONTRIBUTING.md, however, giving more detail about the process, such as rounds of review, time frame, a link to CODEOWNERS, tests that have to pass, etc. help manage contributor expectations. This, along with linking to the Code of Conduct as you currently do, establishes a context for new contributors.

In terms of governance, the Krator maintainers have an issue open for adopting Open Governance. When this is complete, we'd advise bringing it into the documentation.

Website

Criteria	1 = (Is not present or requires significant work)	2	3 = (is present, but needs work)	4	5 = (is executed extremely well or no improvement required)
Branding and design	✅
Case studies/social proof	✅
Maintenance planning	✅

Comments

Note: as Krator does not have a website yet, we did not expect any of these to be done!

• Branding and design: When the logo is ready, we'll be able to select colors, typically inspired by the logo, for backgrounds, links, and design elements such as borders. Sometimes Krator is capitalized, yet other times lowercase. I would recommend using one or the other consistently.

• Case studies/social proof: As you develop Krator, keep an eye out for companies and projects using Krator, and start working with them early to do things like write blog posts about their experiences. As you gather user blog posts over time, submit a ticket to the CNCF Service Desk and we can turn these into a more marketing-friendly case studies section on your site.

• Maintenance planning:
  • Monorepos: Having a docs+code monorepo is risky in the long term, as it couples all docs builds with code builds and vice versa. If docs CI fails because Netlify is temporarily down, for example, this means that all your code builds can potentially fail as well. Coupling docs in a repository with code can also make a code repo's size expand exponentially, especially as projects pick up steam, write more blog posts (with images), and add other multimedia. For these reasons, we recommend housing the documentation in a separate repo.

Final Recommendations

Creating documentation for new users and new contributors

1. Create a landing page that distills at-a-glance how Krator makes the world a better place, how easy it is to use, and how supportive the community is.

2. Create an About page or blog post that tells the Krator back story.

3. One of the most important areas for a documentation site is the Getting Started guide. I'd recommend an introductory page that explains what Krator does and why it was created that a beginner developer could understand.

4. Create a document that shows, step-by-step, how to start using Krator. Provide prerequisites so that potential adopters can know at a glance if adoption is feasible for their circumstances.

5. Document common use cases and give examples, with code on the page (ideally from a linked, working example).

Consider a structure as in the following:

• Site landing page
  • Why Krator makes life easier
  • Ease of use
  • Community (blog link, social media, logos)
• About (origin story: who, where, when, why)
• Getting started
  • Introduction to Krator
    • Project philosophy
  • Prerequisites
  • Quickstart
• Tutorials
  • Configuring Krator
    • Next steps
  • Deploying Krator
    • Next steps
  • Where to get support when using Krator
  • Next steps
• Tasks
  • Using built-in operators
  • Creating your own operators with Krator
• Best practices
• Troubleshooting
  • Error reference if applicable
• API documentation
• Contributing
  • New contributor guide:
    • Where to start
    • How we work
    • Filing and working on issues for the project
    • Where the community is (contacts, meetings)
    • Contributing to docs
    • Where to ask for more help contributing
    • Next steps
  • Cutting releases