Reorder and tidy titles for Rules to Better Technical Documentation

[tiagov8]

Reorders the index in categories/communication/rules-to-better-technical-documentation.mdx so related rules are grouped together, tidies 10 rule titles, refreshes 7 seoDescription fields, and adds one rule to the category.

1. Reorder (commit 1)

Pure reorder — no rules added or removed at this step. Verified the rule set before and after is identical (56 entries, 32 insertions / 32 deletions).

Positions	Theme
1–4	Intro, content quality (unnecessary words, duplication, DRY)
5–9	Voice & instruction wording (active voice, readers/authors, will vs should, Try Again, Bad/Good)
10–14	Spelling, punctuation, dashes
15–18	Terminology & capitalisation (unclear terms, acronyms, tech terms, Scrum)
19–23	Numbers, dates, addresses
24–33	Formatting (prefixes, keywords, quotations, placeholders, symbols, UI, emojis, headings)
34–36	Links & URLs
37–44	Screenshots & diagrams
45–47	File naming & sample names
48–56	Documentation practice, authorship, sensitive info, safety

2. Title cleanups (commits 2, 4 and 5)

Redundant prefixes dropped and several titles reworded (10 in total). Only title: lines changed — no other frontmatter or body content touched.

Before	After
Sample Names - Do you use generic and consistent names on examples?	Do you use generic and consistent sample names on examples?
On-page - Do you use descriptive links?	Do you make your links descriptive?
Numbers - Do you use separators to improve numbers' readability?	Do you use separators to improve numbers' readability?
Reference - Do you use the correct symbols when documenting instructions?	Do you write navigation instructions using the correct symbols?
Do you know the special symbols on your keyboard?	Do you know the special symbols on a keyboard?
Do you use the right character for replaceable text placeholders?	Do you use the right placeholder format for replaceable text?
Do you take a safety step before you delete content?	Do you take a safety step before deleting content?
Do you refer to the reader and author consistently throughout your document?	Do you refer to readers and authors consistently throughout your document?
Do you format quotations to stand out from the main text?	Do you make quotations stand out from the main text?
Do you produce the best End-User Documentation?	Do you choose the right platform for end-user documentation?

3. Add "Do you write content using active voice?" (commit 3)

use-active-voice is now also part of this category, sitting at position 5 — immediately before "Do you refer to readers and authors consistently throughout your document?".

It keeps its existing membership of categories/design/rules-to-better-content-design.mdx; this adds a second category rather than moving it.

The two rules already referenced each other via related in both directions, so no change was needed there.

4. Refresh seoDescriptions (commit 6)

Seven descriptions updated to match the new titles and to fix pre-existing problems.

Rule	Before	After
end-user-documentation	Do you produce the best End-User Documentation?	Compare Word, plain HTML, GitBook, and TinaCMS to choose the right platform for end-user documentation.
refer-consistently-throughout-your-document	When writing technical documentation, consistency in referring to the reader and author is crucial for a flowing reading experience. Ensure accurate referencing throughout your document	Refer to readers and authors consistently throughout technical documentation to keep the reading experience flowing.
style-quotations	Add quotation marks to make them easily identifiable and improve readability by starting a new line with indentation.	Make quotations stand out from the main text using quotation marks, a new line, and indentation to improve readability.
placeholder-for-replaceable-text	Learn the best way to indicate replaceable text in email templates using clear placeholders.	Use a consistent placeholder format to mark replaceable text so readers know exactly what to substitute.
do-you-know-all-the-symbols-on-the-keyboard	Mastering your keyboard's symbols can take you to new levels of typing efficiency and creativity.	Learn the special symbols available on a keyboard and the shortcuts to type them efficiently.
use-correct-symbols-when-documenting-instructions	Use correct symbols when documenting instructions to avoid user confusion and improve understanding by clearly listing steps in the correct order.	Write navigation instructions with the correct symbols so each step reads clearly and in the right order.
use-generic-consistent-names-on-examples	Using consistent and generic names on examples helps maintain confidentiality and professionalism in documentation. This approach enables you to present realistic scenarios without exposing actual clients' information.	Use generic, consistent sample names in examples to present realistic scenarios without exposing real client information.

Why each changed:

• end-user-documentation — the description was the old title verbatim, a question rather than a description. Wrong before this PR; the retitle made it visible.
• refer-consistently — said "the reader and author" (singular), directly contradicting the plural retitle. Also had no closing full stop.
• style-quotations — opened with "Add quotation marks to make them…", a dangling pronoun with no antecedent.
• placeholder-for-replaceable-text — scoped to "email templates", but the rule is general.
• do-you-know-all-the-symbols-on-the-keyboard — used second person ("your keyboard's"), against the repo's neutral/impersonal style guide.
• use-correct-symbols-when-documenting-instructions — did not mention navigation, now the title's focus.
• use-generic-consistent-names-on-examples — ~215 characters, past the ~160 search engines display.

Descriptions left unchanged because they were already accurate: descriptive-links, make-numbers-more-readable, safety-step-when-deleting-content.

Validated with scripts/frontmatter-validator — no errors.

Resulting order

1. Do you know all the cool stuff you can do on SSW Rules?
2. Do you cut unnecessary words from your content?
3. Do you avoid duplicating content?
4. Do you follow DRY and avoid repeated elements in content?
5. Do you write content using active voice?
6. Do you refer to readers and authors consistently throughout your document?
7. Do you use "will", not "should" for processes?
8. Do you use "Try Again" instead of "Retry"?
9. Do you show 'Bad' and 'Good' examples when giving instructions?
10. Do you always check your spelling, grammar, and punctuation?
11. Do you avoid common spelling and syntax mistakes?
12. Do you know commas and full stops should have a single space after them?
13. Do you know the 3 types of dashes?
14. Do you know to use lowercase after "-"?
15. Do you avoid unclear terms?
16. Do you avoid uncommon acronyms in your writing?
17. Do you know to capitalize tech terms correctly?
18. Do you know "Scrum" (and other Scrum terms) should be capitalized?
19. Do you use digits instead of writing out numbers?
20. Do you use separators to improve numbers' readability?
21. Do you avoid short or ambiguous dates?
22. Do you include abbreviated weekdays to dates?
23. Do you know how to format addresses?
24. Prefixes - Do you know why they are awesome?
25. Do you distinguish keywords from surrounding content?
26. Do you make quotations stand out from the main text?
27. Do you use the right placeholder format for replaceable text?
28. Do you write navigation instructions using the correct symbols?
29. Do you strike-through completed items?
30. Do you know the special symbols on a keyboard?
31. Do you know how to format UI elements in technical documentation?
32. Do you use emojis to help give context?
33. Do you know how to capitalize titles and headings?
34. Do you make your links descriptive?
35. Do you know to keep URLs clean?
36. Do you know the difference between a URI, URL, and slug?
37. Do you use screenshots instead of a 'wall of text'?
38. Do you make sure your screenshots are readable?
39. Do you hide visual clutter (toolbars, taskbar, bookmarks, inspector) before taking screenshots?
40. Do you know the best screenshot tools?
41. Do you add branding to screenshots?
42. Do you put borders around white images?
43. Do you use Mermaid diagrams?
44. Do you know how to copy text from an image?
45. Do you know how to name documents/files?
46. Do you avoid using spaces in folder and file names?
47. Do you use generic and consistent sample names on examples?
48. Do you choose the right platform for end-user documentation?
49. Do you have version numbers in documents and design files?
50. Do you document/update processes before sending "Done"?
51. Do you clearly show who last edited a rule or document?
52. Do you acknowledge the authors of published content?
53. Do you use Architectural Decision Records (ADRs)?
54. Do you hide sensitive information?
55. Do you know to highlight the important information on a contract?
56. Do you take a safety step before deleting content?

Note

format-new-lines ("Do you enhance readability with line breaks and spacing?") is isArchived: true, so it does not render on the live page and was not in the requested list. It is kept in the index as the final entry and moved to the end. Happy to remove it entirely if preferred.

🤖 Generated with Claude Code

[github-actions]

🔍 Preview PR Changes

View updated pages in edit mode:

• Rules to Better Technical Documentation
• Do you make your links descriptive?
• Do you know the special symbols on a keyboard?
• Do you choose the right platform for end-user documentation?
• Do you use separators to improve numbers' readability?
• Do you use the right placeholder format for replaceable text?
• Do you refer to readers and authors consistently throughout your document?
• Do you take a safety step before deleting content?
• Do you make quotations stand out from the main text?
• Do you write content using active voice?
• Do you write navigation instructions using the correct symbols?
• Do you use generic and consistent sample names on examples?

Branch: reorder-technical-documentation-rules

[github-actions]

Howzit @tiagov8,

This PR has been here a while.

Did you know you should avoid merge debt?

1. Please action (e.g. get a review) and merge or close

Thanks!