Here's a list of guidelines to consider for a style guide to achieve consistent documentation across different document creators:
Tone and Voice: Define the tone and voice of the documentation. For example, should it be formal or informal? Friendly or neutral? This helps ensure a consistent reading experience.
Language and Grammar: Specify the language (e.g., American English, British English) and grammar rules to follow. Include guidelines on the use of contractions, passive vs. active voice, and punctuation.
Terminology: Establish a glossary of terms specific to your project. This includes acronyms, abbreviations, and industry-specific jargon. Consistent use of terminology helps avoid confusion.
Headings and Structure: Provide a standard structure for documents, including how to use headings, subheadings, and sections. This helps in organizing content logically and makes it easier to navigate.
Code Formatting: Define how code snippets should be formatted and highlighted. Include guidelines on indentation, syntax highlighting, and commenting.
Links and References: Set rules for linking to external resources, citing sources, and referencing other parts of the documentation. This includes guidelines on hyperlink text and formatting.
Images and Media: Provide guidelines for using images, diagrams, and other media. This includes image resolution, file formats, and how to caption and reference images.
Lists and Tables: Define the formatting for lists (bulleted, numbered) and tables. Include guidelines on when to use each and how to format them for clarity.
Accessibility: Ensure your documentation is accessible to everyone, including people with disabilities. Provide guidelines on using alt text for images, accessible colors, and readable fonts.
Version Control: Establish a process for versioning the documentation. This includes how to track changes, update documents, and manage different versions.
Review and Approval: Define a process for reviewing and approving documentation. This includes who is responsible for reviewing, how feedback is provided, and how revisions are made.
Contributing Guidelines: If your project accepts contributions from the community, provide clear guidelines on how to contribute to the documentation. This includes how to submit changes, the review process, and any style or formatting requirements for contributions.
By establishing a comprehensive style guide, you can ensure that your documentation is consistent, clear, and professional, regardless of the number of contributors.
Note issue with lower case file name for images, etc
Inserts of code longer than a page should be in a summary collapsible section - See TMS-Service #159
Mojaloop example: https://docs.mojaloop.io/community/documentation/style-guide.html
ChatGPT suggestion:
Here's a list of guidelines to consider for a style guide to achieve consistent documentation across different document creators: Tone and Voice: Define the tone and voice of the documentation. For example, should it be formal or informal? Friendly or neutral? This helps ensure a consistent reading experience. Language and Grammar: Specify the language (e.g., American English, British English) and grammar rules to follow. Include guidelines on the use of contractions, passive vs. active voice, and punctuation. Terminology: Establish a glossary of terms specific to your project. This includes acronyms, abbreviations, and industry-specific jargon. Consistent use of terminology helps avoid confusion. Headings and Structure: Provide a standard structure for documents, including how to use headings, subheadings, and sections. This helps in organizing content logically and makes it easier to navigate. Code Formatting: Define how code snippets should be formatted and highlighted. Include guidelines on indentation, syntax highlighting, and commenting. Links and References: Set rules for linking to external resources, citing sources, and referencing other parts of the documentation. This includes guidelines on hyperlink text and formatting. Images and Media: Provide guidelines for using images, diagrams, and other media. This includes image resolution, file formats, and how to caption and reference images. Lists and Tables: Define the formatting for lists (bulleted, numbered) and tables. Include guidelines on when to use each and how to format them for clarity. Accessibility: Ensure your documentation is accessible to everyone, including people with disabilities. Provide guidelines on using alt text for images, accessible colors, and readable fonts. Version Control: Establish a process for versioning the documentation. This includes how to track changes, update documents, and manage different versions. Review and Approval: Define a process for reviewing and approving documentation. This includes who is responsible for reviewing, how feedback is provided, and how revisions are made. Contributing Guidelines: If your project accepts contributions from the community, provide clear guidelines on how to contribute to the documentation. This includes how to submit changes, the review process, and any style or formatting requirements for contributions. By establishing a comprehensive style guide, you can ensure that your documentation is consistent, clear, and professional, regardless of the number of contributors.