Peer Reviews

• We're all in this together
  • Be supportive!
• Who edits what?
  • If you're editing something someone on the Dev Enablement team wrote, they should be the one to implement the changes.
    • In general, the author will also be the one to merge a new doc in.
    • Minor changes are more flexible
  • If you're editing something from Product, Sales, Marketing, or even the public, you can just checkout the PR's branch and make edits yourself.
    • That said, if you have any questions, unknowns about the content you can collaborate with its author
• Review process
  • Reviewee:
    • Check finished draft locally
      • For style, grammar, Markdown rendering
      • Remember to check the Hugo front matter:
        • linktitle: Short version of the title that appears in the lefthand nav
        • description: Short description of the content
        • date and lastmod: Dates of initial publication and latest modification.
          • Always update lastmod when you edit an existing doc!
        • tags: avoid making new tags, choose from this list
        • weight: This is the "weight" of content pages in the lefthand nav, higher weights appear lower in lists
    • Sign your commit!
    • Submit a PR in https://github.com/chainguard-dev/edu
      • PR comment should be descriptive
      • Answer all the questions listed to the best of your ability
        • Note: as of August 2024 you should make changes to the repo via a fork
    • Share the PR URL with our assigned reviewer
      • Review rotation can be found in the #dev-enablement-internal slack channel
    • Waits for updates or suggestions from their reviewer
  • Reviewer
    • Give the reviewee a rough sense of when you'll get around to reviewing the draft.
      • Expected turnaround is within 1-3 days, but the author may let you know they need it sooner!
    • Perform a "tech test" on the content
      • This ensures that the procedure and commands outlined work as expected and that any concepts or recommended practices are sound and coherently described.
    • Give a close review of the style, grammar, formatting, markdown etiquette
      • Lean on the Style Guide for this
    • Review the front matter
    • Check out that all the formatting / styling looks okay in the Deploy preview
    • Leave any comments or suggestions in the PR
    • If appropriate, approve the PR. Otherwise leave a comment on the PR asking for changes
  • This process is a two-way street.
    • Both the author and reviewer should be available to answer questions
    • Be nice to each other!
• Broad notes / suggestions
  • Some of these processes are relaxed for small updates
  • If something is time sensitive, the author can push and prod to get it reviewed quickly but it's best to coordinate with someone else ahead of time in cases requiring a quick turnaround
  • We use relative URLs to interlink Academy content