Outline a DocumentIntroduce a DocumentAdd NavigationPrefer task-based headingsProvide text under each headingDisclose information progressively
This section suggests some techniques for planning a larger document
Outline a Document
- Begin with an outline
- Why task — then task.
- Each outline step should either be about a concept or completing a specific task.
- Structure your outline on a need to know basis e.g. Your reader probably doesn’t need to know about the history of the project in the introductions.
- Interactivity: Consider teaching how a concept, just explained can be applied.
- Team: Consider sharing outline with fellow contributors for review.
Outline Exercise
Click to view
Review and update the following high-level outline of an introduction to a long tutorial. To solve this exercise, you can do any of the following:
- Rearrange the existing topics.
- Add any missing topics you feel should be in an introduction.
- Remove any topics you feel are irrelevant for an introduction.
## The history of the project Describes the history of the development of the project. ## Prerequisites Lists concepts the reader should be familiar with prior to starting, as well as any software or hardware requirements. ## The design of the system Describes how the system works. ## Audience Describes who the tutorial is aimed at. ## Setting up the tutorial Explains how to configure your environment to follow the tutorial. ## Troubleshooting Explains how to diagnose and solve potential problems that might occur when working through the tutorial. ## Useful terminology Lists definitions of terms that the reader needs to know to follow the tutorial.
Possible Answer
## Audience Describes who the tutorial is aimed at. ## Prerequisites Lists concepts the reader should be familiar with prior to starting, as well as any software or hardware requirements. ## Setting up the tutorial Explains how to configure your environment to follow the tutorial. ## Useful terminology Lists definitions of terms that the reader needs to know to follow the tutorial.
Introduce a Document
A proper intro should cover the following:
- What the document covers
- What prior knowledge readers are expected to have
- What the document does not cover
Examples and Exercises
Example
This document explains how to publish Markdown files using the Froobus system. Froobus is a publishing system that runs on a Linux server and converts Markdown files into HTML pages. This document is intended for people who are familiar with Markdown syntax. To learn about the syntax, see the Markdown reference. You also need to be comfortable running simple commands in a Linux terminal. This document doesn't include information about installing or configuring a Froobus publishing system. For information on installing Froobus, see Getting started.
Exercise
This guide lists best practices for working with the F@ programming language. F@ was developed in 2011 as an open source community project. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. The programming language is widely adopted in the health industry. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository.
Possible Answers
This guide lists best practices for working with the F@ programming language. F@ was developed in 2011 as an open source community project. This guide is intended for people who are already familiar with the F@ programming language. This document doesn’t include information about installing or configuring the F@ interpreter. For information on installing F@, see Getting started. - My attempt
This guide lists best practices for working with the F@ programming language. Before you review this guide, complete the introductory tutorial for new F@ developers. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository. - Answer by Google
Add Navigation
Providing navigation for your readers ensures they can find what they need when they get stuck.
Clear Navigation?
- Introduction and summary sections
- Clear, logical development of the subject
- Headings and sub-headings that help users understand the subject
- A table of contents that show readers where they are in the document.
- Links to related resources or more in-depth info.
- Links to what to learn next.
Prefer task-based headings
Choose a simple heading that describes the task your reader is working on.
Example
Suppose you are documenting the process of creating a new website.
To create the site, the reader must initialize the Froobus framework. To initialize the Froobus framework, the reader must run the
carambola command-line tool. At first glance, it might seem logical to add either of the following headings to the instructions:- Running the carambola command
- Initializing the Froobus framework
Creating the site is a simpler heading to use in this case unless your readers are very experienced with the terms and concepts for the topic.
Provide text under each heading
Imagine I just left this heading empty. How do u think the heading would feel? — As useless as the text I decided to put under?
Exercise
Improve the following outline
About this tutorial. Advanced topics Build the asset navigation tree Define resource paths Defining and building projects. Launch the development environment. Defining and building resources. What's next. Define image resources. Audience. See also. Build an image resource. Define an image project. Build an image project. Setting up the tutorial Select the tutorial asset root About this guide
Possible answer
## About this tutorial ### Audience ### About this guide ### Advanced topics ## Setting up the tutorial ### Launch the development environment ### Build the asset navigation tree ### Define resource paths ## Defining and building resources ### Define image resources ### Build an image resource ## Defining and building projects ### Define an image project ### Build an image project ## See also ### Sample data files ## What's next
Disclose information progressively
Once again, readers prefer to learn new things on a need to know basis.
Toggle to see how you can incorporate progressive disclosure in your documents
- Try to keep new terms close to instructions reliant on them.
- Use tables, diagrams, lists, headings to help break up large walls of text.
- Break up large series of steps. Consider shorter lists containing sub-tasks.
- Simple — Complex examples and instructions.
Made with Bullet