From 773145720dc6cc4ca26039a85c313df08cc801ec Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Mon, 11 Nov 2019 07:44:30 +1100 Subject: [PATCH] Include @jaredmorgs review of README.md --- README.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index c948b99b..d36a0dd4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # About the Templates Repo -This repository contains best practice templates to help build documention for open source software, which incidentally is directly applicable to other domains too. +This repository contains best-practice templates to help build documentation for open-source software, which incidentally is directly applicable to other domains too. Here we provide tips for using these templates. @@ -13,12 +13,11 @@ The templates are categorised in line with standard [DITA](http://docs.oasis-ope **Reference**: Contains structured information or specifications that users need to make a product work. Reference sections should comprehensively catalog data such as functions and their parameters, return codes and error messages. -Our templates follow these categorizations, and you should find your information naturally chunks this way. - +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. Use recipes to mix templates and create targetted documentation sets for a specific scenarios. +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 that are hot and ready to eat for your readers. When writing your documentation, it helps to think about the following: @@ -26,22 +25,20 @@ When writing your documentation, it helps to think about the following: * What will they be trying to accomplish when they read the documentation? * The information type. Is it a concept, a task or reference? -On the last point, it's best not to add *a lot* of conceptual or task-based information in the middle of your API reference section; however, do make common sense adjustments such as adding comments (which are sort of conceptual) after your examples in an API reference. - ## The templates Templates we currently offer: | Template name | Documentation type | | ---------------------- | ------- | -API Project overview | concept -API Quickstart | task -API Reference | reference -Discussion | concept -How-to | task -Tutorial | task -General reference entry | reference -Logging reference | reference +API Project overview | Concept +API Quickstart | Concept, Task +API Reference | Reference +Discussion | Concept +How-to | Task +Tutorial | Concept, Task +General reference entry | Reference +Logging reference | Reference ## The cookbook