From 2fe48665b0fd4f36c2dddd973bd24aaa04641849 Mon Sep 17 00:00:00 2001 From: Viraji Ogodapola Date: Sun, 13 Dec 2020 00:05:47 +0530 Subject: [PATCH 1/4] Update about-base-template.md Incorporating review comments of PR https://github.com/thegooddocsproject/incubator/pull/14. --- base-template/about-base-template.md | 71 ++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 20 deletions(-) diff --git a/base-template/about-base-template.md b/base-template/about-base-template.md index d5cc426..be34cc8 100644 --- a/base-template/about-base-template.md +++ b/base-template/about-base-template.md @@ -2,17 +2,12 @@ ## Introduction -It's important to document repetitive or iterative processes that you encounter in your routine work. The best documentation uses a formal structure with specified standards, and adheres to predefined style guides. Doing this can sometimes be tedious, futile, and time consuming, so documentation can be random, ad hoc, and of inferior quality and a poor standard. If the documentation is poor quality to begin with, and is frequently edited by random different users, the quality and integrity can become even worse. +This document is used to create a uniform, regulated template for producing multiple similarly structured documents, that is, as a base template to create any other template. The base template guides you through the steps to create a functional template that can be reused, adhered to, and followed consistently throughout. -Documentation must maintain consistency and integrity at all times. This is made easier by using a template for each documentation type. A good template helps you simplify the process of creating any required document. It can save you time and effort, while ensuring consistency, clarity, and uniformity across your documentation suite. +Using a well-defined, good template helps to maintain consistency and integrity across all documentation while simplifying the process of creating any required document. It can save you time and effort, while ensuring consistency, clarity, and uniformity across your documentation suite. The base template goes one step further, in that it helps you create any template for a given document type. It gives you direction in building the required template for a specific use case. -Use the base template to create a uniform, regulated template for producing similarly structured documents for a certain process. It's also useful if you are making process changes that call for identical repetitive changes to documents that are similar in structure. - -The base template guides you through the steps to create a functional template that can be reused, adhered to, and followed consistently throughout. - -However, note that the base template cannot be used to arrive at the document type you need, and is not a substitute for any other template in the collection at the main repository. ## Prerequisites @@ -27,33 +22,69 @@ To make the best use of this base template, you need a working knowledge of: The base template is for: -- Internal users - those who are already working in the Good Docs Project (GDP) -- External users - the community outside of the GDP +- Internal users - The base template is for doc type template authors who wish to align and/or contribute to The Good Docs Project (GDP). +- External users - the community outside of the GDP. Who want to: -- Create new templates that do not yet exist within GDP -- Edit existing templates that require changes +- Create new templates that do not yet exist within the GDP. +- Edit existing templates that require changes. ## How do you know you need the base template The base template is useful when: -- You have identified that the process or document type you are trying to create does not have an existing template in GDP -- You need to make significant changes to an existing GDP template +- You have identified that the process or document type you are trying to create does not have an existing template in the GDP. +- You need to make significant changes to an existing GDP template. - You need to produce multiple, uniformly structured documents that are: - - Reusable, subject to iterative changes - - Sustainable, easily accessible, and maintainable - - Made available to the community freely + - Reusable, subject to iterative changes. + - Sustainable, easily accessible, and maintainable. + - Made available to the community freely. ## What will the base template cover The base template includes: -- An overview of the template you are creating -- Prerequisites, the minimum requirements for accessing or making use of the template -- Procedures, step-by-step instructions to create your template -- Examples, good examples of existing templates +- An overview of the template you are creating. +- Prerequisites, the minimum requirements for accessing or making use of the template. +- Procedures, step-by-step instructions to create your template. + +## Examples + +Given below are two sample use cases that will help you identify whether you need to create a new template/modify an existing one, and how the base template can help you achieve that. + +**Use Case 1** + +Product JKL consists of dynamic and static features. Different developers work on developing the features independently and they are to document the features they worked on, individually. They require a single template to ensure that all documentation for static as well as for dynamic, reflects the same consistency, style of writing, adheres to company guidelines and follows the same style guide and glossary. + +Sandra, the Technical Writer for JKL goes about creating a template for this requirement. She identifies that such a Feature document is a combination of technical reference related to the developed feature, and a how-to guide instructing the user on how to activate the specific feature. The existing templates are not likely to cover this scope fully, and therefore she creates a new How to Add a New Feature template for this purpose. + + +The identifiable points in this process relating to the use of the base template are: + +- Multiple documents with similar content needs to be produced +- The documents consist of elaborate technical references that require different displaying strategies such as tables, formulas, embedded code snippets etc. +- A considerable amount of repetitive content exists within the documents such as the product intro, disclaimer, legal requirements etc. +- The language used must remain consistent throughout and the in-house style guide has to be adhered to. +(For example, always bolden the UI element that follows the verb “click”, use uppercase for tab names etc.) + + +Incorporating the above, Sandra creates a _How to Add a New Feature_ template with two variants, one for static features, and the other for dynamic features accommodating their specific technical reference sections, using the base template. + +**Use Case 2** + +Company PQR provides intermediate service solutions to end customers who use multiple products that are run and used concurrently. PQR specializes in providing 24/7 critical support assisting the technical personnel run a smooth operation that faces a dynamic front end. While the staff of PQR are highly competent in their support service, they do not necessarily have in-depth knowledge in all of the components used by the different products. + +The objective is to provide them with a Standard Operating Procedure (SOP) that will cover all the required technical information and references that a PQR support personnel will need in time of critical system failure. + + +The identifiable variables in this requirement are: +- Multiple documents for different levels of support (critical, medium, low) with just the right level of detail for each. +- Multiple documents each highlighting a different product, but with a similar level of information on the integrated solution. +- Different levels of engagement and competencies by the readers. For example, the SOP will be accessed by a developer to integrate a component different to his, or by a systems administrator trying to ensure all servers are running optimally, or by the end user trying to configure the product at his end. + +Such a document as the above is a combination of all types of documentation, with just the right blend of how-to, technical reference, explanation and tutorial. The base template can be used to create an optimal template for this requirement, which then can be altered as per the level of engagement and competency of the reader. + ## Useful References From ad1abf2bb68adf95a6c85d67986849e7e66f9129 Mon Sep 17 00:00:00 2001 From: Viraji Ogodapola Date: Sun, 13 Dec 2020 00:07:35 +0530 Subject: [PATCH 2/4] Update about-base-template.md Further changes. --- base-template/about-base-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base-template/about-base-template.md b/base-template/about-base-template.md index be34cc8..6cc3d0a 100644 --- a/base-template/about-base-template.md +++ b/base-template/about-base-template.md @@ -22,7 +22,7 @@ To make the best use of this base template, you need a working knowledge of: The base template is for: -- Internal users - The base template is for doc type template authors who wish to align and/or contribute to The Good Docs Project (GDP). +- Internal users - doc type template authors who wish to align and/or contribute to The Good Docs Project (GDP). - External users - the community outside of the GDP. Who want to: From 091ba4512a6df191e6eb3a33e3acc97deb272b27 Mon Sep 17 00:00:00 2001 From: Viraji Ogodapola Date: Sun, 13 Dec 2020 00:26:10 +0530 Subject: [PATCH 3/4] Update base-template.md Editing as per review comments from https://github.com/thegooddocsproject/incubator/pull/14. --- base-template/base-template.md | 138 ++++++++++++--------------------- 1 file changed, 48 insertions(+), 90 deletions(-) diff --git a/base-template/base-template.md b/base-template/base-template.md index ff9c2d6..0c9d98d 100644 --- a/base-template/base-template.md +++ b/base-template/base-template.md @@ -1,117 +1,75 @@ - - + # Base template ## Overview -The base template is a blueprint that outlines any type of template required for a specific documentation type. That is, the base template will guide you through the process of creating a well structured template that can be used to create/standardize multiple documents similar in content. - -Commonly used documentation types that we come across in our routine work can be broadly categorized into how-to guides, tutorials, reference or explanation documents. Any document that you create is likely to either be one of these types or a combination of a few of them. With the help of the base template, you can create a uniform, regulated template for any of these documentation types. +The base captures the structure and common elements that all types of documentation templates associated with The Good Docs Project (GDP) should follow. It includes guidance for downstream template authors to follow when creating a new template. -You are likely to require the base template to create a new template or modify an existing one, if you have identified repetitive, similarly structured content in multiple documents that need to be uniformly structured and aligned to a standardized document. +In our practice, the most commonly used documentation types are of concept, task, and reference. Any document that you create is likely to either be one of these types or a combination of a few of them. With the help of the base template, you can create a uniform, regulated template for any of these documentation types. ## Before you start To be able to make the best of this base template, you should have sufficient knowledge of: -
    -
  1. Technical documentation types - to be able to identify the type of documentation you need to create a template for, or modify the existing one into.
    2. -
  2. Writing technical documentation - to accurately and clearly express instructions to the reader.
    3. -
+ +1. Technical documentation types - to be able to identify the type of documentation you need to create a template for, or modify the existing one into. +2. Writing technical documentation - to accurately and clearly express instructions to the reader. + ## Step-by-step guide This section guides you through on how to create any template using the base template, for a certain type of documentation, in distinguishable steps. -
    -
  1. Identify the content that you need to have a template for. -
    This would be content that is: -
      -
    1. Repetitive/similar in terms of: -
        -
      1. Structure
        2. -
      2. Formatting, styles
        3. -
      3. Procedures
        4. -
      4. Text such as descriptions, disclaimers, snippets etc.
        5. -
      2. + +1. Identify the content that you need to have a template for. + +This would be content that is: +- Repetitive/similar in terms of: + - Structure + - Formatting, styles + - Procedures + - Text such as descriptions, disclaimers, snippets etc. + that can be grouped together, written/presented in the same manner, and reused.

      -
    2. Does not have existing templates to accommodate above.

      3. -
    3. Existing templates require modification to accommodate the above.

    +- Does not have existing templates to accommodate above. +- Existing templates require modification to accommodate the above. -
  2. Identify a prototype, i.e., a suitable sample document that you are going to base your template on. This document will have the most variety of the content that you will be covering, in your template.

    3. +2. Identify a prototype, i.e., a suitable sample document that you are going to base your template on. This document will have the most variety of the content that you will be covering, in your template.
    -
  3. Identify the type of documentation you need to write the template for. This would broadly be one, or a combination of the following types of documentation: -
      -
    • How-to guide
      • -
    • Tutorial
      • -
    • Reference
      • -
    • Explanation

    +3. Identify the type of documentation you need to write the template for. This would broadly be one, or a combination of the following types of documentation: -
  4. Identify the repetitive content in your documents. This could be for instance, -
      -
    • Introduction - a generic intro that gets repeated in all docs. Could be that of the organization, department, documentation etc.
      • -
    • Disclaimers, policies and other legal snippets that are applicable throughout.
      • -
    • Structure and formatting such as headers, footers, font sizes, font types etc.
      • -
    • Processes and procedures.

    +- How-to guide +- Tutorial +- Reference +- Explanation -
  5. Identify your target audience, so as to be able to give clear instructions on creating a new template, from the perspective of your reader.

    6. +4. Identify the repetitive content in your documents. This could be for instance, -
  6. Create the template that you are going to need, giving out step-by-step instructions, in clear, simple language.
    +- Introduction - a generic intro that gets repeated in all docs. Could be that of the organization, department, documentation etc. +- Disclaimers, policies and other legal snippets that are applicable throughout. +- Structure and formatting such as headers, footers, font sizes, font types etc. +- Processes and procedures. -Although the specific template you are creating may vary, ensure that you have covered the basics of a good template.
    +5. Identify your target audience, so as to be able to give clear instructions on creating a new template, from the perspective of your reader. + +6. Create the template that you are going to need, giving out step-by-step instructions, in clear, simple language. + +Although the specific template you are creating may vary, ensure that you have covered the basics of a good template. Some of the essential elements of your template would be: -
      -
    • Title - include a title. The title should be reflective of what your template is for.
      • -
    • Overview - a brief description of what your template can be used for.
      • -
    • Prerequisites / before you start
      • -
    • Procedures
      • -
    • Images / screenshots
      • -
    • Code snippets - include a sample snippet with expected formatting and styles.
      • -
    • Optionally, repetitive content like, organization introduction, disclaimer, glossary etc.
      • -
    • Page structure - header, title, page numbers, table of content etc.
      • -
    • Styles
      • -
    • Directory structure
      • -
    • Naming conventions for directories, files, documents etc.
      • -
    -
    7. -
  7. Use consistent language and tone throughout your docs.

    8. - -
  8. Once you have created the template that you require, you can optionally add it to the existing archive of Good Docs Project Templates, to be used by the wider community. -

- -## Examples -Given below are two sample use cases that will help you identify whether you need to create a new template/modify an existing one, and how the base template can help you achieve that.

-***Use Case 1***
- -Product JKL consists of dynamic and static features. Different developers work on developing the features independently and they are to document the features they worked on, individually. They require a single template to ensure that all documentation for static as well as for dynamic, reflects the same consistency, style of writing, adheres to company guidelines and follows the same style guide and glossary. -Sandra, the Technical Writer for JKL goes about creating a template for this requirement. She identifies that such a Feature document is a combination of technical reference related to the developed feature, and a how-to guide instructing the user on how to activate the specific feature. The existing templates are not likely to cover this scope fully, and therefore she creates a new _How to Add a New Feature_ template for this purpose. -
-The identifiable points in this process relating to the use of the base template are: -
    -
  • Multiple documents with similar content needs to be produced.
    • -
  • The documents consist of elaborate technical references that require different displaying strategies such as tables, formulas, embedded code snippets etc.
    • -
  • A considerable amount of repetitive content exists within the documents such as the product intro, disclaimer, legal requirements etc.
    • -
  • The language used must remain consistent throughout and the in-house style guide has to be adhered to.
    • -For example, always bolden the UI element that follows the verb “click”, use uppercase for tab names etc. - -
- -Incorporating the above, Sandra creates a How to Add a _New Feature template_ with two variants, one for static features, and the other for dynamic features accommodating their specific technical reference sections, using the base template. - -***Use Case 2*** - -Company PQR provides intermediate service solutions to end customers who use multiple products that are run and used concurrently. PQR specializes in providing 24/7 critical support assisting the technical personnel run a smooth operation that faces a dynamic front end. While the staff of PQR are highly competent in their support service, they do not necessarily have in-depth knowledge in all of the components used by the different products. -The objective is to provide them with a Standard Operating Procedure (SOP) that will cover all the required technical information and references that a PQR support personnel will need in time of critical system failure. -
+- Title - include a title. The title should be reflective of what your template is for. +- Overview - a brief description of what your template can be used for. +- Prerequisites / before you start. +- Procedures. +- Images / screenshots. +- Code snippets - include a sample snippet with expected formatting and styles. +- Optionally, repetitive content like, organization introduction, disclaimer, glossary etc. +- Page structure - header, title, page numbers, table of content etc. +- Styles +- Directory structure +- Naming conventions for directories, files, documents etc. + +7. Use consistent language and tone throughout your docs. -The identifiable variables in this requirement are: -
    -
  • Multiple documents for different levels of support (critical, medium, low) with just the right level of detail for each.
    • -
  • Multiple documents each highlighting a different product, but with a similar level of information on the integrated solution.
    • -
  • Different levels of engagement and competencies by the readers.
    -For example, the SOP will be accessed by a developer to integrate a component different to theirs, or by a systems administrator trying to ensure all servers are running optimally, or by the end user trying to configure the product at their end.
    • -
-Such a document as the above is a combination of all types of documentation, with just the right blend of how-to, technical reference, explanation and tutorial. The base template can be used to create an optimal template for this requirement, which then can be altered as per the level of engagement and competency of the reader. ## Useful References From 67d235c387046fcb67c70a9f73bb39f6c5eca56c Mon Sep 17 00:00:00 2001 From: Viraji Ogodapola Date: Sun, 13 Dec 2020 00:28:48 +0530 Subject: [PATCH 4/4] Update base-template.md Further changes --- base-template/base-template.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/base-template/base-template.md b/base-template/base-template.md index 0c9d98d..0dffa00 100644 --- a/base-template/base-template.md +++ b/base-template/base-template.md @@ -25,17 +25,15 @@ This would be content that is: - Structure - Formatting, styles - Procedures - - Text such as descriptions, disclaimers, snippets etc. - -that can be grouped together, written/presented in the same manner, and reused.
-
+ - Text such as descriptions, disclaimers, snippets etc. +that can be grouped together, written/presented in the same manner, and reused. + - Does not have existing templates to accommodate above. - Existing templates require modification to accommodate the above. -2. Identify a prototype, i.e., a suitable sample document that you are going to base your template on. This document will have the most variety of the content that you will be covering, in your template.
+2. Identify a prototype, i.e., a suitable sample document that you are going to base your template on. This document will have the most variety of the content that you will be covering, in your template. 3. Identify the type of documentation you need to write the template for. This would broadly be one, or a combination of the following types of documentation: - - How-to guide - Tutorial - Reference