Skip to main content

Style Guide

This style guide provides guidelines and best practices for maintaining a consistent and cohesive writing style across all documentation and content produced for Hyletic.

Tone and Voice​

  • Professional: Maintain a professional tone to establish credibility and authority.
  • Positive: Be positive and optimistic in your writing to create a motivating and encouraging atmosphere.

Grammar and Punctuation​

  • Grammar: Use proper grammar and sentence structure to ensure clarity and readability.
  • Punctuation: Follow standard punctuation rules for commas, periods, semicolons, etc. to enhance the flow and understanding of the content.
  • Capitalization: Use sentence case for headings and subheadings. Capitalize proper nouns and titles.

Formatting and Styling​

  • Headings: Use headings and subheadings to organize content and improve readability. Follow the hierarchy of headings (e.g., Heading 1, Heading 2, Heading 3).
  • Lists: Use bullet points or numbered lists to present information in a concise and structured manner.
  • Bold and Italics: Use bold and italics to highlight important terms, keywords, or phrases.
  • Code: Format code snippets using monospace font and distinguish them from regular text by using code blocks or inline code formatting.
  • Links: Use descriptive anchor text for hyperlinks and ensure that they are properly formatted and functional.

Terminology and Glossary​

  • Consistency: Use consistent terminology throughout the documentation to avoid confusion.
  • Glossary: Maintain a glossary of key terms and concepts related to Hyletic. Provide definitions and explanations for these terms to help readers understand the content better.

Capitalize Brand Names​

Brand names such as "Apple" and "Slack" are proper nouns, so they should usually be capitalized. If a brand name uses unusual capitalization, as in "eBay" and "VMware", then follow the brand's convention.

Links from the Handbook should conform to a few general guidelines:

  • Linked text should describe the content to which the link leads. A page title or description is usually a good choice and preferable to something like "this" or "here".
  • Link URLs should not result in unnecessary redirection. HTTP redirection can be helpful, especially for handling external links and bookmarks, but it is better for link and bookmark reliability (and sometimes loading speed) to skip redirection whenever possible.
  • Link URLs should not specify default file names or extensions unless excluding them would result in redirection. Overly specific link URLs are more likely to break in response to future changes.
  • Same-site links should use root-relative URLs, not absolute URLs or document-relative URLs.
  • Same-page URLs should just be fragment identifiers (e.g., #link-guidelines).
  • For SEO purposes, try to have links open in a new tab. You can do this by adding the {:target="_blank"} link attribute to the end of an inline link. Ex: [Text to display](link){:target="_blank"}

See Understanding Absolute and Relative URLs for more information about each type of URL.

Images and Graphics​

  • Relevance: Use images and graphics that are relevant to the content and enhance understanding.
  • Quality: Ensure that images and graphics are of high quality and clearly visible.
  • Captions: Provide descriptive captions for images and graphics to provide context and additional information.

Accessibility​

  • Clear and Concise: Write in a clear and concise manner to ensure accessibility for all readers, including those with disabilities or language barriers.
  • Alt Text: Provide alternative text (alt text) for images and graphics to make them accessible to screen readers.
  • Readability: Use a readable font size and style. Break down long paragraphs into shorter, more digestible sections.

Review and Editing​

  • Proofreading: Proofread all content for grammatical errors, spelling mistakes, and typos.
  • Consistency: Ensure consistent use of style, tone, and terminology throughout the documentation.
  • Clarity: Review the content for clarity and organization. Make revisions to improve understanding and flow.

By following this style guide, we can ensure that our documentation and content maintain a consistent and professional style, providing a positive user experience for our readers and users.