Skip to content

Latest commit

 

History

History
259 lines (182 loc) · 6.71 KB

technical-writing.md

File metadata and controls

259 lines (182 loc) · 6.71 KB

Technical Writing Guide

Introduction

Technical writing is a specialized form of writing focused on communicating complex technical information clearly and effectively. This guide provides standards and best practices for creating high-quality technical content across all Bayat projects.

Core Principles

Clarity

  • Use simple, direct language
  • Define technical terms when first used
  • Break complex ideas into smaller, manageable parts
  • Focus on one main idea per paragraph

Accuracy

  • Verify all technical information
  • Include version numbers where relevant
  • Cite sources for external information
  • Maintain consistency in terminology

Audience Awareness

  • Identify your audience before writing
  • Adjust technical depth based on audience expertise
  • Consider cultural and language differences
  • Address the audience's goals and needs

Structure

  • Organize content with a clear hierarchy
  • Use descriptive headings and subheadings
  • Present information in a logical sequence
  • Include navigation aids for longer documents

Voice and Tone

Standard Voice

  • Professional but conversational
  • Active voice (preferred over passive)
  • Second person ("you") for instructions
  • Confident but not authoritative

Contextual Tone Adjustments

  • Tutorials: Encouraging and step-by-step
  • Reference materials: Precise and neutral
  • Troubleshooting guides: Empathetic and solution-oriented
  • API documentation: Concise and technical

Document Types

Tutorials

  • Start with clear prerequisites
  • Include a working example
  • Break into discrete, achievable steps
  • Explain the why behind actions
  • End with next steps or further learning

How-to Guides

  • Focus on specific tasks
  • Use numbered steps for sequential procedures
  • Include examples for complex steps
  • Add troubleshooting tips for common issues

Conceptual Documentation

  • Explain ideas and abstract concepts
  • Use analogies to simplify complex topics
  • Include diagrams and visual aids
  • Connect concepts to practical applications

Reference Documentation

  • Organize for quick information retrieval
  • Use consistent formatting for similar items
  • Include all relevant parameters and options
  • Link to related concepts and examples

Release Notes

  • Categorize changes (new features, improvements, bug fixes)
  • Highlight breaking changes prominently
  • Include migration instructions when needed
  • Use consistent versioning references

Writing Style Guidelines

Sentences and Paragraphs

  • Use short to medium-length sentences (15-25 words)
  • Limit paragraphs to 3-5 sentences
  • Use transitional phrases between paragraphs
  • Vary sentence structure to maintain interest

Word Choice

  • Use consistent terminology throughout
  • Avoid jargon unless necessary for the audience
  • Replace idioms with direct language
  • Choose specific over general terms

Lists

  • Use bulleted lists for unordered items
  • Use numbered lists for sequential steps
  • Keep list items parallel in structure
  • Aim for 3-7 items per list

Tables

  • Use tables to organize complex information
  • Include clear column headers
  • Align numerical data appropriately
  • Provide a descriptive caption

Formatting Standards

Typography

  • Use sentence case for headings
  • Apply consistent heading hierarchy
  • Use bold for emphasis (sparingly)
  • Use italics for defined terms and UI elements

Code Formatting

  • Use monospace font for code
  • Include syntax highlighting where possible
  • Clearly distinguish inline code from surrounding text
  • Provide complete, runnable examples

Links

  • Use descriptive link text (not "click here")
  • Indicate external links consistently
  • Verify links regularly
  • Group related links at the end of sections

Images and Diagrams

  • Use high-quality, accessible images
  • Include descriptive alt text
  • Add captions explaining the image purpose
  • Maintain consistent style across diagrams

Accessibility

Text Accessibility

  • Use sufficient color contrast
  • Don't rely solely on color to convey information
  • Use descriptive headings for screen readers
  • Avoid directional references ("below" or "right")

Media Accessibility

  • Provide transcripts for audio content
  • Add captions to video content
  • Create alt text for all meaningful images
  • Make diagrams screenreader-compatible

Document Structure

  • Use proper heading hierarchy (H1, H2, H3)
  • Create accessible tables with headers
  • Use semantic HTML when publishing online
  • Test documents with accessibility tools

Review Process

Self-Review

  • Wait at least one hour before self-reviewing
  • Read content aloud to catch awkward phrasing
  • Check for consistency in terminology and style
  • Verify all examples work as described

Peer Review

  • Request technical review from subject matter experts
  • Seek editorial review for clarity and style
  • Include accessibility review in the process
  • Document and track feedback systematically

User Testing

  • Test documentation with target audience members
  • Observe users following documentation
  • Collect structured feedback
  • Iterate based on user experience

Tools and Templates

Recommended Tools

  • Markdown for standard documentation
  • Asciidoc for complex technical documentation
  • Mermaid or PlantUML for diagrams
  • Grammarly or similar for grammar checking

Templates

  • Project README template
  • API documentation template
  • Tutorial template
  • Troubleshooting guide template

Versioning and Maintenance

Version Control

  • Store documentation in the same repository as code
  • Version documentation alongside software releases
  • Tag documentation changes in commits
  • Track major documentation revisions

Maintenance Schedule

  • Review documentation at least quarterly
  • Update with each major software release
  • Archive obsolete documentation
  • Establish ownership for ongoing maintenance

Localization Considerations

Writing for Translation

  • Use simple sentence structures
  • Avoid culturally specific references
  • Provide context for translators
  • Allow for text expansion in layouts

Translation Management

  • Maintain glossaries for consistent terminology
  • Provide style guides for translators
  • Include translation memory in the workflow
  • Test translated documentation with target audiences

Resources