{"id":382,"date":"2015-04-14T15:33:50","date_gmt":"2015-04-14T19:33:50","guid":{"rendered":"https:\/\/lios.dev.creationsunivers.net\/the-topic-based-method-giving-good-directions\/"},"modified":"2015-04-14T15:33:50","modified_gmt":"2015-04-14T19:33:50","slug":"the-topic-based-method-giving-good-directions","status":"publish","type":"post","link":"https:\/\/lios.dev.creationsunivers.net\/en\/the-topic-based-method-giving-good-directions\/","title":{"rendered":"The Topic-based Method: Giving Good Directions"},"content":{"rendered":"

As any travel writer knows, readers must be lead to the right destination with suggested itineraries to help them make the most of their trip. The same principle applies to technical writers using the topic-based method. They have to organize the various topics to guide users through their tasks. After all, as Marc Achtelig<\/a> says, your content may be fantastic, but if it can\u2019t be found and is poorly structured, your document won\u2019t be used.<\/p>\n

\"\"<\/p>\n

Many roads<\/h4>\n

There are many ways to organize topics. For instance, Tom Johnson lists a dozen or so ways for online support here<\/a>. Ideally, good organization works for many users, reflects their thought process and meets their needs. However, each user is different and has his or her own set of experiences, skills and knowledge. How can we set up an organization that works for all? First, establishing one or more typical user profiles will help (to learn more, see our article Identifying Your Audience<\/a>). It\u2019s also important to take the product or the service being documented into account.<\/p>\n

Only three, please!<\/h4>\n

Even with documentation containing hundreds of topics, try to flatten the structure as much as possible. To do this, present a topic at its highest level and keep it to three levels. Since several topics will be at the same level of the Table of Contents or in the navigation menus, be sure to give your readers reference points so they find what they\u2019re looking for quickly.<\/p>\n

\"\"<\/p>\n

 <\/p>\n

For example, start your titles with keywords. Making sure your titles follow a pattern will also help people get straight to the point. This means titles for topics with similar content will follow a similar pattern (e.g., \u201cDownloading the application\u201d and \u201cDownloading the drivers\u201d). Titles should be written differently, however, according to the type of topic (concept, task, reference). The title designates the topic and the type of information being presented. In a guide on nautical safety, for instance, we might find the following titles :<\/p>\n

\u00a0(Level 1) On-water Safety Rules<\/strong><\/h4>\n

(Level 2) Safety requirements for nautical equipment<\/h4>\n

(Level 3) Safety requirements for boats<\/span>
\nRequirements for floating device<\/span>s
\nRequirements for fishing equipment<\/span><\/p>\n

Down with disorder!<\/h4>\n

Users perceive information differently according to how it is presented. So start with the most important information, both in the Table of Contents and the topic\u2019s navigational menu. Put essential information\u2014like what users will look for most frequently or the information they need to understand everything else\u2014at the beginning. Complementary information comes next, followed by all other potentially useful information. Different types of topics should be organized with the concepts placed at the beginning, followed by tasks and ending with references.<\/p>\n

Links to take you further<\/h4>\n

In the topic-based method, links between topics are important. Like bridges connecting islands and allowing travellers to easy cross from one to the next, links will guide your users to other possibly interesting subjects. Links are references to other topics (in the same document or in \u201cAlso see\u2026\u201d type text) or specific sections. With on-line documentation, clickable links make the user\u2019s task all the easier since they lead directly to the right place. Other navigational tools (ex., Last topic\/Next topic) also help users go from one topic to the next and influence the order in which they consult the various topics.<\/p>\n

Clarity first<\/h4>\n

Information should always be organized so users quickly find what they\u2019re looking for. This is why even if this organization aims for a certain logic, it must always put clarity before standardization. Even the best itinerary won\u2019t lead anywhere if people can\u2019t follow it!<\/p>\n","protected":false},"excerpt":{"rendered":"

As any travel writer knows, readers must be lead to the right destination with suggested itineraries to help them make the most of their trip. The same principle applies to technical writers using the topic-based method. They have to organize the various topics to guide users through their tasks. After all, as Marc Achtelig says, […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[28,23],"tags":[],"class_list":["post-382","post","type-post","status-publish","format-standard","hentry","category-information-architecture","category-technical-writing-and-documentation"],"acf":[],"_links":{"self":[{"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/posts\/382","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/comments?post=382"}],"version-history":[{"count":0,"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/posts\/382\/revisions"}],"wp:attachment":[{"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/media?parent=382"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/categories?post=382"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/lios.dev.creationsunivers.net\/en\/wp-json\/wp\/v2\/tags?post=382"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}