Topic based writing from idea to output
Download as PPTX, PDF3 likes685 views
The document discusses topic-based writing as a modern approach to documentation, emphasizing the creation of standalone, reusable content that can be delivered in various formats across multiple devices. It highlights the advantages of modular information, which allows users to access only the information they need, in the order they prefer. The presentation also mentions using DITA as a standard for structuring information effectively and discusses methods for creating and publishing documents using various software tools.
Topic based writing from idea to output
- 1. Bernard Aschwanden www.publishingsmarter.com [email protected] VIDEO of this presentation is also available https://www.youtube.com/watch?v=yE9cjNxiqMs Topic-Based Writing: From Idea to Output 17:44 1 @publishsmarter
- 2. What to expect 17:44@publishsmarter Text-rich, illustration-heavy, table-filled, overly-hyphenated manuals and docs sit on the shelf and never get read Today, we read information in the format we want, on whatever device we want, and with just enough information to support what we need to do Learn more about topic-based writing, what it is and what it can do for your approach to documentation Any device, any time, any format Smaller chunks of information, topic types, reusable, assembled as needed, delivered in any format Explore the idea of topic- based writing, single-sourcing materials, and replacing some text with audience friendly information We'll create a sample document set, update materials in many software tools, and deliver PDF, XHTML, web-friendly, multi- device, platform independent information 2
- 3. Standard disclaimer 17:44@publishsmarter In the interest of brevity I will make some blanket statements to keep it simple It’s not all 100% “the truth”, but I’ll stay close Purists may complain And they are wrong! (except when they are right) In the interest of time and content I’ll go quickly 3
- 4. But what if it’s too fast? 17:44@publishsmarter 4 No worries as it’s all recorded Slides are online as well at: http://www.slideshare.net/PublishingSmarter/topic-based- writing-from-idea-to-output And the video to go with this is online too! https://www.youtube.com/watch?v=yE9cjNxiqMs
- 5. What it is, where it matters, how to get there @publishsmarter 17:44 5 Topic-based writing
- 6. What it is 17:44@publishsmarter 6 A way to create content from standalone topics each of which is: Smallest possible unit of information that makes sense on its own (no absolute dependencies) Reusable as a standalone unit of information Based on information type (concept, reference, task) Can be assembled to create help, HTML, PDF, etc Linked and referenced to build relationships
- 7. Modular means: Pieces of information must make sense without context Pieces of information can be moved around Context may or may not bring extra meaning to individual pieces 17:44 7 @publishsmarter
- 8. Thinking in topics 17:44@publishsmarter 8 In the past Content flowed from first, to second, to third Dependencies created to ‘before’ and ‘after’ content Difficult to reuse or reorganize with ease With topic-based writing Content becomes discrete, stand-alone unit of info No concept of ‘before’ or ‘after’ but rather ‘related’ Context of use may modify the message
- 9. Benefits of topic-based content for users 17:44@publishsmarter 9 Read what you want Read in the order you want Common layout makes it fast to scan and find content (beyond search) Right information, right format, right time Information is in topic types, each with a purpose Task: How to complete a goal Concept: Why a goal is worth achieving, or what it is Reference: Quick lookup or guide to technical specs
- 10. Sometimes you can say more by not saying anything at all @publishsmarter 17:44 10 Text substitution
- 11. Tables 17:44@publishsmarter 11 Best used in reference materials Short, concise comparisons In tasks, avoid If… Then… approach Generally these are tasks or broken out Consider substeps Some may be reference info instead If documenting issues, fix the UI In electronic docs these may also be able to sort content based on user requests
- 12. Sample keyboard shortcuts 17:44@publishsmarter 12 Function Modifier Key Icon Notes Cut Ctrl x Places selected content on the clipboard. Copy Ctrl c Places selected content on the clipboard. Paste Ctrl v Places clipboard content at the insertion point. Font edit Ctrl+Shift f Opens the font dialog to edit text appearance. Function Modifier Key Icon Notes Copy Ctrl c Places selected content on the clipboard. Font edit Ctrl+Shift f Opens the font dialog to edit text appearance. Paste Ctrl v Places clipboard content at the insertion point. Cut Ctrl x Places selected content on the clipboard. Sort by Key Default sort as presented (grouped by functions)
- 13. Value of an image 17:44@publishsmarter Rather than text The breather is located on top of the pump and is usually capped in black. Consider this: Rather than text The valve is located between the main tank and the exhaust pipe. Consider this: 13
- 14. Complex image with a callout table 17:44@publishsmarter 14 # Name # Name A Revolving nosepiece F Arm B Objective G Stage C Stage clips H Coarse adjustment knob D Diaphragm I Fine adjustment knob E Light source J Base A B C D E F G H I J
- 15. Orient users in large images 17:44@publishsmarter 15 Step 2: Use the dipstick to check lubricant levels
- 16. Organize information 17:44@publishsmarter 16 A comparison of average size tells you whales are big: US male is 5’9” US female is 5’4” Beluga whale is 18’ long Blue whale is 98’ long A table can tell you the same thing Mammal Avg length/height Human being 5’7” Beluga whale 18’ Blue whale 98’ 6’ / 2m < 6’ 98’ 18’
- 17. Based on DITA because, well... @publishsmarter 17:44 17 Let’s get into topics
- 18. DITA should matter to you 17:44@publishsmarter 18 A growing standard with vendor support More companies looking for DITA skills Not just structured writing; best practices: Planning content Organizing information Developing relationships Using automation where it makes sense
- 19. Darwin Information Typing Architecture DITA is about Topic, Maps, Specializations Some common topic types include concept reference task glossary bookmap and map 17:44@publishsmarter 19 DITA in a single slide DITA Information Types Topic–Concept–Task–Reference
- 20. Types of topics 17:44@publishsmarter 20 Tasks: Start with tasks (Users don’t want to learn about something unless they have to) What does the user need to do? Identify those and then write how they do it. Concepts: Supporting info for a task In many cases, concepts can provide a clear conceptual model that is lacking in a task. Used to orient the users. References: Quick look up; no procedures, no conceptual information
- 21. Start with tasks 17:44@publishsmarter 21 Odds are people are doing things when they discover a need to look up docs Tasks are the most likely place users turn An answer to how that tells the user just what to do and the order in which to do it Step-by-step instructions that enables a user to actually do something
- 22. Support them with concepts and references 17:44@publishsmarter 22 Concepts explain “what is” or “why would I” info References are more “tech specs”
- 23. For example, if talking about saving files… 17:44@publishsmarter 23 Task Save a file Save a file with a new name, or to another location Concept When you save files, this is what happens Reasons to save files References File formats
- 24. Good question, let’s go play @publishsmarter 17:44 24 What about “hands-on” stuff?
- 25. From the outline 17:44@publishsmarter 25 We'll create a sample document set, update materials in many software tools, and deliver PDF, XHTML, web-friendly, multi-device, platform independent information
- 26. Working the sample documents 17:44@publishsmarter 26 Several tools, using DITA Oxygen to create content XML to edit content FrameMaker to publish content And back again…
- 27. Publish the output 17:44@publishsmarter 27 All the tools allow you to publish content And more are out there
- 28. Summing up the discussion, and options to continue it. @publishsmarter 17:44 28 Conclusion and contact
- 29. Follow up contact information 17:44@publishsmarter 29 905 833 8448 (Eastern Time) [email protected] www.linkedin.com/in/bernardaschwanden @publishsmarter or @aschwanden4stc www.publishingsmarter.com