Check Other Teams’ User Documentation

Your team will review the user documentation of another team.
Treat this as a professional review: give feedback that helps improve clarity, consistency, and fitness for purpose — not just a list of complaints.

Goal

To practice evaluating documentation like a professional reviewer.
Ask yourself: does it meet its audience’s needs? Does the format, content, and tone fit its intended purpose?

No Empty Words

Avoid vague, generic, or copy-pasted reviews. Whether you write it fully yourself or use an assistant tool, the feedback must clearly reflect your own understanding of the specific documentation you read.
Reviews filled with buzzwords or generic praise (“very clear,” “good structure”) without context are worthless.
Use your own words, grounded in real examples from the project — that’s how professionals build credibility.

What to Do

1. Read another team’s user documentation carefully.
   Follow it like a real user would. Note what feels clear, confusing, or missing.

2. Create a GitLab issue in their repository titled
   Review: User Documentation – from Team [Your Team Name].

   • Assign your tutor to the issue.
   • Write your comments directly in the issue, organized into short sections.

3. Cover these three aspects in your review:

Fit for Purpose

• Is the documentation format (tutorial, how-to, explanation, reference) suitable for what it aims to do?
• Is it in the right place and accessible to the intended readers?
• Example: internal developer notes are fine inside internal docs, but not as “user manuals.”
• External documentation may include internal drafts if it’s clearly marked (e.g. “Draft for future web publication”).
  Since you are not expected to host servers or build full publication environments, content quality and clarity are the main focus.

Audience Suitability

• Is the content written in the audience’s language and domain?
• Does it assume the right level of background knowledge?
• Does it ever ask readers to do something they should never do (like editing source code or rebuilding the app)?
• Give concrete examples for both good and bad matches.

Technical and Stylistic Suggestions

• Recommend specific documentation features (steps, tables, diagrams, links, code blocks).
• Suggest practical style or tool improvements (Markdown features, Sphinx autodoc, screenshots, formatting).

• Keep your feedback polite, direct, and actionable.

• Conclude with “Highlights and Next Steps.”

  • Mention two or three strong points you appreciated.
  • Then list two or three actionable improvements.

Timing and Verification

• Submit your review as a GitLab issue no later than one week before the final in-team point-splitting.
• Notify your tutor in person before or after class so they can verify and award any extra points.

Extra Points

Teams can earn up to 5 extra points for a helpful, constructive, and specific review.
The team you reviewed may also choose to transfer up to 5 of their own extra points to you if they found your feedback particularly useful.

Example Review Snippet

Fit for Purpose
The documentation is structured as a how-to guide, which fits well for its goal of showing end users how to run the data import script. The Markdown layout is clear, but the section on prerequisites reads more like internal developer notes. Consider moving that part to your developer docs or flagging it as “for maintainers.”

Audience Suitability
The explanations use domain language (“dataset schema,” “API key”) correctly and at an appropriate level for technical users. However, avoid lines like “build the binary” — an end user won’t have the environment to do that.

Technical & Stylistic Suggestions
Add a code block for the example command and a screenshot of the expected output. This will make the steps easier to follow.

Highlights and Next Steps
✅ Clear structure and tone.
✅ Good use of examples.
🔧 Move developer content out of user docs.
🔧 Add a short troubleshooting section for failed imports.