Docs Philosophy

All of Chainguard’s documentation, tutorials, and other educational resources should have the following characteristics:

Purpose

• Explains why someone would find value in reading the given content
• Communicates technical knowledge that is useful and relevant to users
• Communicates any assumptions regarding the reader’s technical level at the top to set expectations
  • Ideally, we want to educate the broadest audience possible, but this is not always possible in practice
• Well-scoped
  • Provides enough detail of information for a given topic
  • Is not overwhelming to read
  • Breaks down complex topics into accessible, digestible pieces
• Encourages readers to put knowledge into practice
  • Provides concrete examples and opportunities to “play” (through something like the terminal, for instance) in order to improve the audience's retention of information
• Provides guidance for further learning
• Is community-centric
  • Supports open source
  • Supports developer collaboration
  • Supports growing the technical community
• Aligns with Chainguard’s company values
  • We are customer obsessed
  • We have a bias for intentional action
  • We do serious work, but don't take ourselves too seriously
  • We trust each other and assume good intentions

Technical details

• Is correct, accurate, and without copy errors or bugs
• Follows software security recommended practices
• Is up to date with the latest version, or tied to a specific version
• Explains code thoroughly
  • Readers should not be asked to run commands or code that they do not fully understand
  • Links to further reading if not everything can be covered in one document
• Provides compelling, realistic examples
  • If possible, use concrete examples from open source projects
• Avoid using placeholder names that are meaningless, like foo and bar
• Is logically structured and helps the reader follow a procedure or understand a concept from beginning to end
• Is original and well researched
  • Resources are original and not syndicated from elsewhere
  • However, they can be syndicated elsewhere where Chainguard has the canonical link
• Links the source when a resource is quoted
• Is not plagiarized
• All written text is licensed under CC BY-NC-SA 4.0
  • Any future syndication must maintain the license
  • The license enables language translations
  • Others may build off of our resources
  • Creative Commons is in the spirit of open source

Tone

• Has an authentic developer voice that is welcoming and inclusive
• Is friendly but formal
• Prioritizes objectivity
• Avoids making value judgments (for example, “This tool is great!“)
• Can make substantiated recommendations
• Uses American English spellings
• Uses clear language
  • Does not use idiomatic expressions
  • Avoids jokes or puns that detract from the meaning or educational value of the resource (there is more room for humor in content types like videos or presentations)
  • Is accessible to many readers
  • Aims towards machine translatability
• Is grammatically correct
• Has no errors in copy
• Provides punctuation that helps with readability

Inclusivity and Accessibility

• Is written with readers who use accessibility tools in mind
  • Avoids terms like “look,” “see,” and “view”. For example, you could use “this command will return output like the following” instead of “you’ll see the following output”
  • Avoids directional language. Use terms like “following” and “previous” instead of “below” and “above”
• Ensures that images (photos, not container images) always include descriptive alt text, and are descriptively named
• Avoids colloquialisms and region-centric analogies
  • Uses inclusive language
  • Google’s developer documentation style guide has in-depth guidelines on using inclusive language in a technical document

These principles guide authors to create conceptual articles, tutorials, and other learning resources that help our readers better understand how Chainguard’s products work.