diff --git a/categories/communication/rules-to-better-technical-documentation.mdx b/categories/communication/rules-to-better-technical-documentation.mdx index 0070278ba17..a6a6726f4c1 100644 --- a/categories/communication/rules-to-better-technical-documentation.mdx +++ b/categories/communication/rules-to-better-technical-documentation.mdx @@ -5,61 +5,62 @@ uri: rules-to-better-technical-documentation guid: 961f2035-1540-4425-9b29-0d6273ac0726 index: - rule: public/uploads/rules/rule/rule.mdx - - rule: public/uploads/rules/safety-step-when-deleting-content/rule.mdx - - rule: public/uploads/rules/do-you-avoid-duplicating-content/rule.mdx - rule: public/uploads/rules/avoid-using-unnecessary-words/rule.mdx + - rule: public/uploads/rules/do-you-avoid-duplicating-content/rule.mdx + - rule: public/uploads/rules/avoid-repetition/rule.mdx + - rule: public/uploads/rules/use-active-voice/rule.mdx + - rule: public/uploads/rules/refer-consistently-throughout-your-document/rule.mdx + - rule: public/uploads/rules/use-will-not-should/rule.mdx + - rule: public/uploads/rules/use-try-again-instead-of-retry/rule.mdx + - rule: public/uploads/rules/use-bad-and-good-examples/rule.mdx - rule: public/uploads/rules/are-you-careful-with-your-spelling-grammar-and-punctuation/rule.mdx - rule: public/uploads/rules/avoid-common-mistakes/rule.mdx - - rule: public/uploads/rules/avoid-repetition/rule.mdx - - rule: public/uploads/rules/avoid-acronyms/rule.mdx + - rule: public/uploads/rules/commas-and-full-stops-always-should-have-1-space-after-them/rule.mdx + - rule: public/uploads/rules/dashes/rule.mdx + - rule: public/uploads/rules/use-lowercase-after-a-dash/rule.mdx - rule: public/uploads/rules/avoid-unclear-terms/rule.mdx - - rule: public/uploads/rules/avoid-short-ambiguous-dates/rule.mdx + - rule: public/uploads/rules/avoid-acronyms/rule.mdx + - rule: public/uploads/rules/use-the-right-capitalization/rule.mdx + - rule: public/uploads/rules/scrum-should-be-capitalized/rule.mdx - rule: public/uploads/rules/use-digits-instead-of-words/rule.mdx - rule: public/uploads/rules/make-numbers-more-readable/rule.mdx + - rule: public/uploads/rules/avoid-short-ambiguous-dates/rule.mdx + - rule: public/uploads/rules/add-days-to-dates/rule.mdx + - rule: public/uploads/rules/address-formatting/rule.mdx - rule: public/uploads/rules/prefixes/rule.mdx - - rule: public/uploads/rules/use-emojis/rule.mdx - - rule: public/uploads/rules/format-new-lines/rule.mdx - - rule: public/uploads/rules/formatting-ui-elements/rule.mdx - rule: public/uploads/rules/distinguish-keywords-from-content/rule.mdx - - rule: public/uploads/rules/placeholder-for-replaceable-text/rule.mdx - rule: public/uploads/rules/style-quotations/rule.mdx - - rule: public/uploads/rules/descriptive-links/rule.mdx - - rule: public/uploads/rules/keep-your-urls-clean/rule.mdx + - rule: public/uploads/rules/placeholder-for-replaceable-text/rule.mdx - rule: public/uploads/rules/use-correct-symbols-when-documenting-instructions/rule.mdx - - rule: public/uploads/rules/address-formatting/rule.mdx - - rule: public/uploads/rules/use-the-right-capitalization/rule.mdx + - rule: public/uploads/rules/do-you-strike-through-completed-items/rule.mdx + - rule: public/uploads/rules/do-you-know-all-the-symbols-on-the-keyboard/rule.mdx + - rule: public/uploads/rules/formatting-ui-elements/rule.mdx + - rule: public/uploads/rules/use-emojis/rule.mdx - rule: public/uploads/rules/how-to-capitalize-titles/rule.mdx - - rule: public/uploads/rules/scrum-should-be-capitalized/rule.mdx - - rule: public/uploads/rules/commas-and-full-stops-always-should-have-1-space-after-them/rule.mdx - - rule: public/uploads/rules/dashes/rule.mdx - - rule: public/uploads/rules/use-lowercase-after-a-dash/rule.mdx - - rule: public/uploads/rules/use-will-not-should/rule.mdx - - rule: public/uploads/rules/use-try-again-instead-of-retry/rule.mdx - - rule: public/uploads/rules/use-bad-and-good-examples/rule.mdx + - rule: public/uploads/rules/descriptive-links/rule.mdx + - rule: public/uploads/rules/keep-your-urls-clean/rule.mdx + - rule: public/uploads/rules/uri-url-slug/rule.mdx + - rule: public/uploads/rules/screenshots-avoid-walls-of-text/rule.mdx - rule: public/uploads/rules/readable-screenshots/rule.mdx - rule: public/uploads/rules/hide-visual-clutter-in-screenshots/rule.mdx - rule: public/uploads/rules/screenshots-tools/rule.mdx - - rule: public/uploads/rules/screenshots-avoid-walls-of-text/rule.mdx - rule: public/uploads/rules/screenshots-add-branding/rule.mdx - rule: public/uploads/rules/borders-around-white-images/rule.mdx - - rule: public/uploads/rules/refer-consistently-throughout-your-document/rule.mdx + - rule: public/uploads/rules/use-mermaid-diagrams/rule.mdx + - rule: public/uploads/rules/copy-text-from-image/rule.mdx - rule: public/uploads/rules/how-to-name-documents/rule.mdx - rule: public/uploads/rules/remove-spaces-from-your-folders-and-filename/rule.mdx - rule: public/uploads/rules/use-generic-consistent-names-on-examples/rule.mdx + - rule: public/uploads/rules/end-user-documentation/rule.mdx - rule: public/uploads/rules/show-version-numbers/rule.mdx - rule: public/uploads/rules/document-the-job/rule.mdx - - rule: public/uploads/rules/end-user-documentation/rule.mdx - - rule: public/uploads/rules/highlighting-important-contract-terms/rule.mdx - - rule: public/uploads/rules/architectural-decision-records/rule.mdx - - rule: public/uploads/rules/hide-sensitive-information/rule.mdx - - rule: public/uploads/rules/do-you-know-all-the-symbols-on-the-keyboard/rule.mdx - - rule: public/uploads/rules/copy-text-from-image/rule.mdx - rule: public/uploads/rules/making-last-edited-clear/rule.mdx - - rule: public/uploads/rules/add-days-to-dates/rule.mdx - - rule: public/uploads/rules/use-mermaid-diagrams/rule.mdx - - rule: public/uploads/rules/uri-url-slug/rule.mdx - - rule: public/uploads/rules/do-you-strike-through-completed-items/rule.mdx - rule: public/uploads/rules/do-you-always-acknowledge-your-work/rule.mdx + - rule: public/uploads/rules/architectural-decision-records/rule.mdx + - rule: public/uploads/rules/hide-sensitive-information/rule.mdx + - rule: public/uploads/rules/highlighting-important-contract-terms/rule.mdx + - rule: public/uploads/rules/safety-step-when-deleting-content/rule.mdx + - rule: public/uploads/rules/format-new-lines/rule.mdx created: 2015-12-11T22:57:52.000Z createdBy: Tiago Araujo createdByEmail: TiagoAraujo@ssw.com.au diff --git a/public/uploads/rules/descriptive-links/rule.mdx b/public/uploads/rules/descriptive-links/rule.mdx index 9db8e6bcdc5..7f32082cd23 100644 --- a/public/uploads/rules/descriptive-links/rule.mdx +++ b/public/uploads/rules/descriptive-links/rule.mdx @@ -20,7 +20,7 @@ related: - rule: public/uploads/rules/wcag-compliance/rule.mdx seoDescription: Descriptive links improve website SEO and provide a friendly experience to users. -title: On-page - Do you use descriptive links? +title: Do you make your links descriptive? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx - category: categories/design/rules-to-better-websites-navigation.mdx diff --git a/public/uploads/rules/do-you-know-all-the-symbols-on-the-keyboard/rule.mdx b/public/uploads/rules/do-you-know-all-the-symbols-on-the-keyboard/rule.mdx index eaf771e366f..cadfe89ab0d 100644 --- a/public/uploads/rules/do-you-know-all-the-symbols-on-the-keyboard/rule.mdx +++ b/public/uploads/rules/do-you-know-all-the-symbols-on-the-keyboard/rule.mdx @@ -1,6 +1,6 @@ --- type: rule -title: Do you know the special symbols on your keyboard? +title: Do you know the special symbols on a keyboard? uri: do-you-know-all-the-symbols-on-the-keyboard categories: - category: categories/communication/rules-to-better-technical-documentation.mdx @@ -13,7 +13,7 @@ related: - rule: public/uploads/rules/rule/rule.mdx redirects: [] guid: 578c55c7-6a02-441a-ba89-9d151be72250 -seoDescription: Mastering your keyboard's symbols can take you to new levels of typing efficiency and creativity. +seoDescription: Learn the special symbols available on a keyboard and the shortcuts to type them efficiently. created: 2019-03-13T01:38:31.000Z createdBy: Sharon Du createdByEmail: Unknown@ssw.com.au diff --git a/public/uploads/rules/end-user-documentation/rule.mdx b/public/uploads/rules/end-user-documentation/rule.mdx index 83ea5e3aae4..99b3e40743f 100644 --- a/public/uploads/rules/end-user-documentation/rule.mdx +++ b/public/uploads/rules/end-user-documentation/rule.mdx @@ -19,8 +19,8 @@ lastUpdatedBy: Greg Harris lastUpdatedByEmail: GregHarris@ssw.com.au redirects: - do-you-produce-the-best-end-user-documentation -seoDescription: Do you produce the best End-User Documentation? -title: Do you produce the best End-User Documentation? +seoDescription: Compare Word, plain HTML, GitBook, and TinaCMS to choose the right platform for end-user documentation. +title: Do you choose the right platform for end-user documentation? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule diff --git a/public/uploads/rules/make-numbers-more-readable/rule.mdx b/public/uploads/rules/make-numbers-more-readable/rule.mdx index cf2e8489761..55b0e0bea8f 100644 --- a/public/uploads/rules/make-numbers-more-readable/rule.mdx +++ b/public/uploads/rules/make-numbers-more-readable/rule.mdx @@ -18,7 +18,7 @@ related: - rule: public/uploads/rules/right-format-to-show-phone-numbers/rule.mdx seoDescription: Use separators to improve numbers' readability and make large sums or phone numbers easier to comprehend. -title: Numbers - Do you use separators to improve numbers' readability? +title: Do you use separators to improve numbers' readability? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx - category: categories/design/rules-to-better-interfaces-general-usability-practices.mdx diff --git a/public/uploads/rules/placeholder-for-replaceable-text/rule.mdx b/public/uploads/rules/placeholder-for-replaceable-text/rule.mdx index f8890baa0d7..368bff26dec 100644 --- a/public/uploads/rules/placeholder-for-replaceable-text/rule.mdx +++ b/public/uploads/rules/placeholder-for-replaceable-text/rule.mdx @@ -1,6 +1,6 @@ --- type: rule -title: Do you use the right character for replaceable text placeholders? +title: Do you use the right placeholder format for replaceable text? uri: placeholder-for-replaceable-text categories: - category: categories/communication/rules-to-better-technical-documentation.mdx @@ -19,7 +19,7 @@ related: redirects: - how-to-indicate-replaceable-text guid: 3c146b39-4bb1-4da1-845a-2f4d936d19ec -seoDescription: Learn the best way to indicate replaceable text in email templates using clear placeholders. +seoDescription: Use a consistent placeholder format to mark replaceable text so readers know exactly what to substitute. created: 2022-07-29T17:13:28.570Z createdBy: Tiago Araujo createdByEmail: TiagoAraujo@ssw.com.au diff --git a/public/uploads/rules/refer-consistently-throughout-your-document/rule.mdx b/public/uploads/rules/refer-consistently-throughout-your-document/rule.mdx index 83e8520dc5b..4ae3e92bcdc 100644 --- a/public/uploads/rules/refer-consistently-throughout-your-document/rule.mdx +++ b/public/uploads/rules/refer-consistently-throughout-your-document/rule.mdx @@ -16,10 +16,8 @@ redirects: related: - rule: public/uploads/rules/use-the-right-order-of-instructions/rule.mdx - rule: public/uploads/rules/use-active-voice/rule.mdx -seoDescription: 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 -title: Do you refer to the reader and author consistently throughout your document? +seoDescription: Refer to readers and authors consistently throughout technical documentation to keep the reading experience flowing. +title: Do you refer to readers and authors consistently throughout your document? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule diff --git a/public/uploads/rules/safety-step-when-deleting-content/rule.mdx b/public/uploads/rules/safety-step-when-deleting-content/rule.mdx index a369e0d5fb8..b2c0b67c262 100644 --- a/public/uploads/rules/safety-step-when-deleting-content/rule.mdx +++ b/public/uploads/rules/safety-step-when-deleting-content/rule.mdx @@ -10,7 +10,7 @@ related: - rule: public/uploads/rules/inform-about-content-deletion/rule.mdx seoDescription: When deleting content, take a safety step by pasting it into an email thread and inform others to ensure easy recovery. -title: Do you take a safety step before you delete content? +title: Do you take a safety step before deleting content? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule diff --git a/public/uploads/rules/style-quotations/rule.mdx b/public/uploads/rules/style-quotations/rule.mdx index 0bc307464a4..c9383ca423e 100644 --- a/public/uploads/rules/style-quotations/rule.mdx +++ b/public/uploads/rules/style-quotations/rule.mdx @@ -17,9 +17,8 @@ related: - rule: public/uploads/rules/indent/rule.mdx - rule: public/uploads/rules/distinguish-keywords-from-content/rule.mdx - rule: public/uploads/rules/use-quotations/rule.mdx -seoDescription: Add quotation marks to make them easily identifiable and improve readability - by starting a new line with indentation. -title: Do you format quotations to stand out from the main text? +seoDescription: Make quotations stand out from the main text using quotation marks, a new line, and indentation to improve readability. +title: Do you make quotations stand out from the main text? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule diff --git a/public/uploads/rules/use-active-voice/rule.mdx b/public/uploads/rules/use-active-voice/rule.mdx index 2fcfb2662b1..9668ac111f1 100644 --- a/public/uploads/rules/use-active-voice/rule.mdx +++ b/public/uploads/rules/use-active-voice/rule.mdx @@ -22,6 +22,7 @@ seoDescription: Write compelling and engaging content using active voice to get title: Do you write content using active voice? categories: - category: categories/design/rules-to-better-content-design.mdx + - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule uri: use-active-voice --- diff --git a/public/uploads/rules/use-correct-symbols-when-documenting-instructions/rule.mdx b/public/uploads/rules/use-correct-symbols-when-documenting-instructions/rule.mdx index 65325dc92c8..cac42a661ff 100644 --- a/public/uploads/rules/use-correct-symbols-when-documenting-instructions/rule.mdx +++ b/public/uploads/rules/use-correct-symbols-when-documenting-instructions/rule.mdx @@ -17,9 +17,8 @@ related: - rule: public/uploads/rules/distinguish-keywords-from-content/rule.mdx - rule: public/uploads/rules/make-numbers-more-readable/rule.mdx - rule: public/uploads/rules/awesome-documentation/rule.mdx -seoDescription: Use correct symbols when documenting instructions to avoid user confusion - and improve understanding by clearly listing steps in the correct order. -title: Reference - Do you use the correct symbols when documenting instructions? +seoDescription: Write navigation instructions with the correct symbols so each step reads clearly and in the right order. +title: Do you write navigation instructions using the correct symbols? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule diff --git a/public/uploads/rules/use-generic-consistent-names-on-examples/rule.mdx b/public/uploads/rules/use-generic-consistent-names-on-examples/rule.mdx index 67c32d2a0b9..33573082573 100644 --- a/public/uploads/rules/use-generic-consistent-names-on-examples/rule.mdx +++ b/public/uploads/rules/use-generic-consistent-names-on-examples/rule.mdx @@ -15,10 +15,8 @@ lastUpdatedBy: Olivia Westmacott lastUpdatedByEmail: OliviaWestmacott@sswcom.onmicrosoft.com redirects: - do-you-use-generic-and-consistent-names-on-examples -seoDescription: 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. -title: Sample Names - Do you use generic and consistent names on examples? +seoDescription: Use generic, consistent sample names in examples to present realistic scenarios without exposing real client information. +title: Do you use generic and consistent sample names on examples? categories: - category: categories/communication/rules-to-better-technical-documentation.mdx type: rule