From 91ca9755c622d317986798de25a225c505a10934 Mon Sep 17 00:00:00 2001 From: Loquacity Date: Sat, 13 Jun 2020 12:17:09 +1000 Subject: [PATCH 1/2] readme edits to C/T/R --- README.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bc83addb..0db08b3b 100644 --- a/README.md +++ b/README.md @@ -4,36 +4,49 @@ This repository contains best-practice templates to help build documentation for Here we provide tips for using these templates. + ## Core documentation types -The templates are categorised in line with standard [DITA](http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/technicalContent/dita-technicalContent-InformationTypes.html#dita_technicalContent_InformationTypes) documentation types: +The templates are categorised into three documentation types: -**Concept**: Describes how and why things work. -Concepts are normally written to help the reader understand a technology, prior to using it. +**Concept**: +Describes how and why something works. +Concepts answer the question "what is it?". +When readers read concepts, they are learning about a topic. +Use concepts to help the reader understand a technology, before they start using it. -**Task**: Gives specific instructions about how to get something done. -In practice, Tasks tend to have a specific goal and usually consist of a set of numbered steps that the reader can follow to achieve the goal. +**Task**: +Gives specific instructions about how to get something done. +Tasks answer the question "how do I do it?". +When readers read tasks, they are doing something. +Tasks tend to have a specific goal and consist of a set of numbered steps that the reader can follow to achieve that goal. -**Reference**: Contains structured information or specifications that users need to make a product work. +**Reference**: +Contains structured information or specifications that users need to make a product work. +Reference material answers the question "what else do I need to know?" +When readers read references, they are fact-checking. Reference sections should comprehensively catalog data such as functions and their parameters, return codes and error messages. +They are often presented as tables, bulleted lists, or sample scripts. Our templates follow these documentation types, and you should find that your information naturally fits into them as you write. + ## How to use these templates -We like to compare documentation types to aisles in a grocery store. -Each aisle includes related templates, which you can think of as ingredients. +We like to compare documentation types to aisles in a grocery store. +Each aisle includes related templates, which you can think of as ingredients. Use these ingredients in documentation cookbooks to whip up docs for your readers. -When writing your documentation, it helps to think about the following: +When writing your documentation, it helps to think about: * Who are you writing for? -* What will they be trying to accomplish when they read the documentation? -* The information type. Is it a concept, a task or reference? +* What will they be trying to do when they read the documentation? +* What information are you providing? Is it a concept, a task, or reference? + ## The templates -Templates we currently offer: +Templates we offer: | Template name | Documentation type | | ---------------------- | ------- | From aa4fb0adedac129ab22baefedbedfdeb40850a63 Mon Sep 17 00:00:00 2001 From: Loquacity Date: Mon, 15 Jun 2020 11:09:25 +1000 Subject: [PATCH 2/2] americanize --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0db08b3b..c9d5ad3e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Here we provide tips for using these templates. ## Core documentation types -The templates are categorised into three documentation types: +The templates are categorized into three documentation types: **Concept**: Describes how and why something works.