Learnings - Timo Reymann

Google Technical Writing Two

The webinar consisted of two parts:

• pre class self-learning
• classroom session

My notes combine both parts into key areas.

Organizing larger documents

• Split large documents info focus areas
  • How to Guides
  • Overview pages
  • Conceptual pages
• Combine multiple documentations into a reference page. Especially when the target audience are engineers that are already familiar with the product or service and just need a quick reference.

Outline for documents

• Always start with an outline in large documents.

• Get feedback on the outline from crew before starting to write the document.
  • Ensure it covers the needs of the audience.
• Verify the written document against the outline after finishing the document.
  • Ensures that the document is not missing any key points.
  • Ensures that the document is not going off track.

Introduction for documents

• Always start with an introduction.

• Should answer the following questions:

  • What is the document about?
  • What does it cover?
  • What does it not cover?
  • What knowledge is required to understand the document?

Navigation

• Provide instruction and summary sections.
• Maintain a clear heading structure, always use appropriate heading levels.
• Link to related documents and resources, also externally.
• Add a “What to learn next?” at the bottom of the document.

Headings

• Prefer task-based structure instead of a technology or feature-based one.
  • “How to create a token” instead of “Create a token with frumbus”.
• Break up large tasks in smaller subtasks.

Illustrations

• Create the caption before working on the illustration.
• Avoid creating illustrations that can’t be explained with more than 5 bullet points.
• Drill down with illustrations, don’t try to explain everything in one illustration.
• Make sure accessibility is given for all illustrations.
  • Alt text for images.
  • Textual description for complex illustrations.
  • Use of colorblind friendly colors.
• Arrows should always be used to indicate a flow, only pointing in one direction.

Sample code

• Should be complete and working.
• Comments should only be added for non-obvious parts.

Creating good drafts

• Always start with a draft.

• Create headings for the document first, before filling in the content.
  • Ensures that the document is structured.
  • Ensures that the document is not missing any key points.
• Work on drafts in the following cycle:
  • Reorganize: Move headings and sections around.
  • Revise: Check for consistency and completeness.
  • Remember: Check for negative spaces.
    • Avoid unnecessary repetition and jargon that is not needed.
    • Avoid over-explaning simple concepts.
    • Avoid explaining implicit information that examples could cover.

This site is open source. Improve this page.