Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleExample

Section
show-titlefalse
titleContext

Readers need to assume that the documentation is written by s single person. This reduces distraction so that readers are able to concentrate on the content and find information easily.

Section
show-titlefalse
titleProblem
Panel

How can a team organize themselves to document in a common style?

Section
titleStructure

Publishing content from different authors is conducted by newspapers and magazines on a regular basis. These organizations employ style guides to deliver quality content. But style guides exists for many other industries, too.

Consistency in written documents increases the ease of reading.

A style guide provides answers to questions to support writers. These include

  • Word choice and controlled vocabulary
  • Mood and tone
  • Product names, Abbreviations, and acronyms
  • Capitalization and Punctuation
  • Spelling and grammar
  • Use of text formatting and typographical conventions
  • Use of diagrams and graphics
  • Use of templates and categories
  • Information Architecture
  • Maintenance procedures
  • Source code organization, naming, and formatting

There may be different or adjusted style guides for different types of text. For instance the tone of answers in social media networks may be different to that found in printed manuals.

A style guide are constantly adapted and expanded. Problems authors encounter while writing should be noted and discussed. These discussions may result in an updated version of the style guide.

...