toss Technical Writing Guide

The Technical Writing Guide provides fundamental writing skills for developers. It is organized into several key areas to help you create, structure, and refine documentation:

• Document Types (/type/index): Understand different types of documentation and the design points that change based on the document's purpose.
• Information Architecture (/architecture/index): Learn how to effectively organize the structure of your documentation.
• Sentence Refinement (/sentence/index): Learn how to convey information using natural and clear sentences.

To get started, you can follow the Quick Start guide or the Basic Documents Tutorial.

Technical Writing is the practice of communicating technical information accurately and effectively. Unlike general writing, which focuses on expressing emotions, ideas, or imagination to inspire readers, Technical Writing focuses on:

1. Goal Orientation: Helping the reader solve problems and achieve specific goals.
2. Efficiency: Delivering information quickly and accurately.
3. Clarity: Prioritizing information transfer over creative expression.

Because reference documentation can be vast, use the following strategies to prevent information overload and improve the user experience:

• Thematic Sectioning: Divide the documentation into logical sections based on topics. Provide a sidebar or table of contents (e.g., an API list for a specific domain like 'Payments') to allow quick jumping between endpoints.
• Strategic Information Placement: Place prerequisite information at the beginning of the document. Before a user dives into specific API references, they often need to know about:
  • API Key configuration
  • Authentication methods
  • Required request headers

Placing these core details upfront ensures users don't miss critical setup steps when they first encounter your documentation.

Cross-linking strengthens the connectivity between documents and allows readers to navigate naturally to related information when they need deeper context.

For example, if a tutorial briefly mentions 'Code Splitting', you should provide a link to a more detailed guide or reference document (e.g., lazy-loading.md) so the reader can find the information immediately when required.

nextjs-performance-optimization/
├── index.md
├── code-splitting.md
├── ...
└── lazy-loading.md # Related content linked from code-splitting

To ensure high readability, easy maintenance, and a simple document structure, follow the principle of focusing each document on a single core goal.

Key Guidelines:

• Avoid deep heading hierarchies: If your heading depth reaches #### (H4) or deeper, it is a signal that the document is becoming too complex and should be split into multiple pages.
• Use Overview pages: If you need to introduce multiple related concepts, create an 'Overview' page that provides a high-level summary and links to individual, detailed documents for each concept.
• Focus on specific topics: If a single page attempts to cover two or more distinct core topics, split them into separate documents.

Checklist for splitting documents:

• Does the heading depth reach #### (H4)? If yes, consider splitting.
• Are there two or more core themes being addressed? If yes, split them.

To reduce cognitive load and help readers find information quickly, technical documentation must be predictable. Predictability is achieved through consistent terminology, natural flow of explanation, and logical information hierarchy.

Predictable documentation provides three main benefits:

1. Faster Navigation: Consistent structures allow readers to find what they need without confusion.
2. Reduced Learning Curve: Consistent headings and paragraph structures allow readers to apply knowledge from previous documents to new ones.
3. Easier Maintenance: Consistent patterns make it easy for teams to decide where new information should be placed.

Effective technical writing focuses on helping readers solve problems and achieve goals by delivering information quickly and accurately. The guide breaks down the writing process into three core pillars:

1. Determine Document Type: Identify if you are writing an API reference, a tutorial, an FAQ, etc. Each type has a specific structure that helps reorganize knowledge effectively for the reader.
2. Create Information Architecture: Design the structure from the reader's perspective rather than focusing on what you want to say. Well-structured information reduces the cognitive effort required to understand new knowledge.
3. Refine Sentences: Even with good structure, poor sentence construction hinders delivery. Focus on writing sentences that are easy to read and easy to write from a technical writing perspective.

Problem-solving documentation is categorized into two main types based on the reader's intent:

How-to Guides

Focus on providing step-by-step procedures and executable code examples to help a reader successfully complete a specific task. Unlike tutorials, How-to guides are not intended to teach overall concepts or flows, but rather to facilitate the successful execution of a specific goal.

Troubleshooting Documents

Focus on diagnosing an issue that has already occurred. The emphasis is on the debugging process and resolving existing problems.

While similar, learning documentation typically falls into two distinct categories:

• Getting Started documents: Aimed at helping new users understand the main flow and core concepts. They should include simple installation/setup guides and essential workflows to provide a high-level overview.
• Tutorial documents: More specific than 'Getting Started' guides, tutorials have a clear goal and a tangible end product. They are structured so that users learn concepts naturally by following steps and executing code to achieve a specific result.

Note: These categories are not rigid. If installation and setup are extremely simple, they are often included at the beginning of a tutorial.