Technical Writing and Documentation 101: Collaboration and Review (GitHub PRs, Figma Comments, Editorial Workflows)

Collaboration and Review (GitHub PRs, Figma Comments, Editorial Workflows)

Collaboration & Review in Technical Writing: A Portfolio-Ready Study Guide

(GitHub PRs, Figma Comments, Editorial Workflows)

What This Is

Collaboration and review are the backbone of modern technical writing. They ensure documentation is accurate, consistent, and user-focused by involving engineers, designers, and other stakeholders early and often. Without structured review workflows, docs risk becoming outdated, confusing, or misaligned with the product.

Real-world example:
Imagine you’re documenting a payment gateway API (like Stripe or PayPal). Your getting-started guide must explain authentication, error codes, and rate limits—but engineers might update endpoints without telling you, designers might tweak UI flows, and support teams might flag confusing terminology. A GitHub PR-based review process lets engineers validate your API examples, Figma comments help you sync with designers on screenshots, and an editorial workflow ensures consistency before publishing.

Key Terms & Tools

• Pull Request (PR) / Merge Request (MR):
  A GitHub/GitLab feature where writers propose changes to documentation (or code) in a branch, allowing teammates to review, comment, and approve before merging. Example: A PR for updating an API reference after a breaking change.

• Docs-as-Code:
  Treating documentation like software: stored in Git, written in Markdown/AsciiDoc, built with static site generators (e.g., Sphinx, Docusaurus, MkDocs), and reviewed via PRs. Tools: GitHub, GitLab, Bitbucket.

• OpenAPI (Swagger):
  A standard for describing REST APIs in YAML/JSON. Enables auto-generated docs (via Swagger UI, ReDoc, or Redocly) and interactive API explorers. Example: A swagger.yaml file that powers your API reference.

• Static Site Generator (SSG):
  A tool that converts Markdown/AsciiDoc files into HTML websites. Examples: Docusaurus (Facebook), Hugo, Sphinx (Python), Next.js (for docs with React).

• Figma Comments:
  Annotations in Figma (a design tool) where writers can flag outdated screenshots, request alt text, or clarify UI flows. Use case: A designer updates a dashboard layout, and you leave a comment: “This screenshot needs a caption for accessibility.”

• Editorial Workflow:
  A structured process for drafting, reviewing, and publishing docs. Often includes stages like Draft → Tech Review → Editorial Review → Published. Tools: Google Docs (with comments), Notion, Confluence, or GitHub Projects.

• Markdown Linting:
  Automated checks for Markdown formatting (e.g., consistent headers, links, or code blocks). Tools: markdownlint, Vale, or Prettier.

• Continuous Integration/Continuous Deployment (CI/CD) for Docs:
  Automating doc builds, tests, and deployments (e.g., running vale on PRs to catch style errors). Example: A GitHub Action that builds your docs site and deploys it to Netlify or Vercel on merge.

• Diátaxis Framework:
  A documentation system that categorizes content into tutorials, how-to guides, explanations, and reference (created by Daniele Procida). Key distinction: A tutorial teaches concepts by building (e.g., “Build a payment form”), while a how-to guide solves a specific problem (e.g., “Handle declined payments”).

• Swagger UI vs. ReDoc:

• Swagger UI: Interactive API explorer with a “Try it out” button (good for developers).

• ReDoc: Cleaner, more readable static docs (better for reference material).

• DITA (Darwin Information Typing Architecture):
  An XML-based standard for modular, reusable documentation (common in enterprise tech writing). Use case: A hardware manual where the same safety warning appears in multiple guides.

• Vale:
  A style linter for prose (e.g., enforcing “use active voice” or “avoid ‘simply’”). Example: A Vale rule that flags passive voice in your docs.

Step-by-Step / Process Flow

How to Collaborate on Docs Using GitHub PRs

1. Set Up Your Local Environment
2. Clone the docs repo: git clone [repo-url]
3. Install dependencies (e.g., npm install for Docusaurus, pip install -r requirements.txt for Sphinx).

4. Run a local build (npm start or make html) to preview changes.

5. Create a Branch for Your Changes

6. Branch naming convention: docs/[feature] (e.g., docs/add-payment-api).

7. Command: git checkout -b docs/add-payment-api

8. Draft Your Content

9. Write in Markdown/AsciiDoc (e.g., payment-api.md).

10. Include:

    
    
    • A clear title (e.g., “Process a Payment”).
    • Code examples (e.g., curl or SDK snippets).
    • Screenshots (exported from Figma, with alt text).
    • Callouts (e.g., > Note: This endpoint is rate-limited.).

11. Test Your Changes

12. Verify links work (markdown-link-check).
13. Test code examples in Postman or the API sandbox.

14. Run a local build to check for errors.

15. Submit a PR for Review

16. Push your branch: git push origin docs/add-payment-api
17. Open a PR in GitHub/GitLab with:
    • A descriptive title (e.g., “Add payment API reference”).
    • A summary of changes (use a template like this).
    • Labels (e.g., docs, api, needs-review).

18. Tag reviewers (e.g., @engineering-team @ux-team).

19. Address Feedback

20. Respond to comments (e.g., “Fixed the 404 error example—thanks @dev!”).
21. Push updates to the same branch (no new PR needed).

22. Use GitHub’s “Resolve conversation” to track progress.

23. Merge and Deploy

24. After approvals, merge the PR.
25. CI/CD pipeline (e.g., GitHub Actions) auto-deploys the updated docs.

How to Sync with Designers via Figma

1. Request Access to the Design File
2. Ask the designer to share the Figma file (or a Figma Community link).

3. Install the Figma desktop app for better performance.

4. Leave Contextual Comments

5. Click on a UI element (e.g., a button) and add a comment:
   > “This ‘Submit Payment’ button is now blue—update the screenshot in payment-guide.md.”

6. Use @mentions to notify the designer (e.g., @jane-design).

7. Export Assets

8. Right-click a frame → Copy/Paste as PNG (or use Export for SVG).

9. Add alt text in your docs (e.g., ![Payment form with credit card fields](payment-form.png)).

10. Follow Up

11. Check Figma for replies (or enable email notifications).
12. Update your PR with the new screenshots.

Editorial Workflow Example

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Collaboration Artifacts
2. Include screenshots of PRs (e.g., a GitHub PR with engineer feedback) or Figma comments in your portfolio.

3. Example: “Here’s how I updated the API docs after a breaking change, with engineer validation.”

4. Process Documentation

5. Write a short case study (e.g., “How I Improved Our Docs Review Process”) with:

   
   
   • The problem (e.g., “Docs were always outdated”).
   • Your solution (e.g., “Added CI/CD checks for OpenAPI specs”).
   • The result (e.g., “Reduced doc bugs by 40%”).

6. Tool Proficiency

7. Be ready to explain:

   
   
   • How you’d set up a docs-as-code workflow (e.g., “I’d use Docusaurus + GitHub Actions + Vale”).
   • The difference between Swagger UI and ReDoc (see Key Terms).
   • How you’d handle a last-minute design change (e.g., “I’d update Figma comments and file a PR”).

8. Tricky Distinctions

9. Tutorial vs. How-To Guide:
   • Tutorial: “Build a payment form from scratch” (teaches concepts).
   • How-To: “Handle declined payments” (solves a specific problem).
10. Reference vs. Guide:
    • Reference: API endpoint descriptions (e.g., GET /payments).
    • Guide: Step-by-step instructions (e.g., “Integrate the Payments API”).

Quick Check Questions

1. Scenario: A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
2. Answer: Implement CI/CD checks (e.g., a GitHub Action that validates OpenAPI specs against the codebase) and automated testing (e.g., run curl examples in a pipeline).

3. Why: Automation catches discrepancies early, and PR reviews ensure human validation.

4. Scenario: A designer updates a UI flow, but the screenshots in your docs are now wrong. What’s your next step?

5. Answer: Leave a Figma comment tagging the designer, export the new assets, and update the PR with the corrected screenshots.

6. Why: Figma comments create a paper trail, and updating the PR keeps changes atomic.

7. Scenario: Your PR has 20+ comments from engineers. How do you prioritize feedback?

8. Answer: Address functional issues first (e.g., broken code examples), then clarity/grammar, and finally nitpicks (e.g., comma placement).
9. Why: Fixing critical errors first ensures the docs are accurate before polishing.

Last-Minute Cram Sheet

1. Docs-as-Code = Git + Markdown + SSG + PRs. ⚠️ Don’t write docs in Word—use Git.
2. OpenAPI 3.0 vs. 2.0: 3.0 supports callbacks, links, and better examples. ⚠️ Always use 3.0+.
3. Markdown linting: Use markdownlint to catch inconsistent headers (## vs ###).
4. Figma shortcuts:
5. C = Comment tool.
6. Shift + 2 = Zoom to selection.
7. PR templates: Include a checklist (e.g., “Did you test code examples?”).
8. Vale rules: Enforce “use active voice” and “avoid ‘simply’/‘just’.”
9. Swagger UI vs. ReDoc: Swagger = interactive; ReDoc = pretty static docs.
10. Diátaxis: Tutorials = teach; How-Tos = solve; Reference = list; Explanation = why.
11. CI/CD for docs: Automate builds, linting, and deployments (e.g., GitHub Actions).
12. ⚠️ A tutorial is not a how-to guide. Tutorials build understanding; how-tos solve problems.