Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Commit

Permalink
Update base-template.md
Browse files Browse the repository at this point in the history 
Editing as per review comments from thegooddocsproject/incubator#14.
  • Loading branch information
@viraji
viraji authored and Cameron Shorter committed Feb 28, 2021
1 parent 9d30cae commit f121f1a
Showing 1 changed file with 48 additions and 90 deletions.
138 changes: 48 additions & 90 deletions base-template/base-template.md
View file
Original file line number Diff line number Diff line change
@@ -1,117 +1,75 @@
<!-- Copy this Template. -->
<!-- Describe the title of your article by replacing "Base Template" with the page name you want to publish to. -->

# 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:
<ol>
<li>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.</li>
<li>Writing technical documentation - to accurately and clearly express instructions to the reader.</li>
</ol>

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.</li>
2. Writing technical documentation - to accurately and clearly express instructions to the reader.</li>


## 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.
<ol>
<li>Identify the content that you need to have a template for.
<br>This would be content that is:
<ol>
<li>Repetitive/similar in terms of:
<ol>
<li>Structure</li>
<li>Formatting, styles</li>
<li>Procedures </li>
<li>Text such as descriptions, disclaimers, snippets etc.</li>
</ol></li>

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.<br>
<br>
<li>Does not have existing templates to accommodate above.</li><br>
<li>Existing templates require modification to accommodate the above.</li></ol><br>
- Does not have existing templates to accommodate above.
- Existing templates require modification to accommodate the above.

<li>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.</li><br>
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.</li><br>

<li>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:
<ul>
<li>How-to guide</li>
<li>Tutorial</li>
<li>Reference</li>
<li>Explanation</li></ul><br>
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:

<li>Identify the repetitive content in your documents. This could be for instance,
<ul>
<li>Introduction - a generic intro that gets repeated in all docs. Could be that of the organization, department, documentation etc.</li>
<li>Disclaimers, policies and other legal snippets that are applicable throughout.</li>
<li>Structure and formatting such as headers, footers, font sizes, font types etc.</li>
<li>Processes and procedures. </li></ul><br>
- How-to guide
- Tutorial
- Reference
- Explanation

<li>Identify your target audience, so as to be able to give clear instructions on creating a new template, from the perspective of your reader.</li><br>
4. Identify the repetitive content in your documents. This could be for instance,

<li>Create the template that you are going to need, giving out step-by-step instructions, in clear, simple language. <br>
- 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. <br>
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:
<ul>
<li>Title - include a title. The title should be reflective of what your template is for. </li>
<li>Overview - a brief description of what your template can be used for.</li>
<li>Prerequisites / before you start </li>
<li>Procedures</li>
<li>Images / screenshots</li>
<li>Code snippets - include a sample snippet with expected formatting and styles.</li>
<li>Optionally, repetitive content like, organization introduction, disclaimer, glossary etc.</li>
<li>Page structure - header, title, page numbers, table of content etc.</li>
<li>Styles</li>
<li>Directory structure</li>
<li>Naming conventions for directories, files, documents etc.</li>
</ul>
</li>
<li>Use consistent language and tone throughout your docs.</li><br>

<li>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.
</ol><br>

## 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.<br><br>
***Use Case 1***<br>

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.

<br>
The identifiable points in this process relating to the use of the base template are:
<ul>
<li>Multiple documents with similar content needs to be produced.</li>
<li>The documents consist of elaborate technical references that require different displaying strategies such as tables, formulas, embedded code snippets etc.</li>
<li>A considerable amount of repetitive content exists within the documents such as the product intro, disclaimer, legal requirements etc.</li>
<li>The language used must remain consistent throughout and the in-house style guide has to be adhered to. </li>
For example, always bolden the UI element that follows the verb “click”, use uppercase for tab names etc.
</li>
</ul>

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.
<br>
- 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</li>
- Directory structure</li>
- Naming conventions for directories, files, documents etc.

7. Use consistent language and tone throughout your docs.

The identifiable variables in this requirement are:
<ul>
<li>Multiple documents for different levels of support (critical, medium, low) with just the right level of detail for each.</li>
<li>Multiple documents each highlighting a different product, but with a similar level of information on the integrated solution.</li>
<li>Different levels of engagement and competencies by the readers. <br>
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.</li>
</ul>
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

Expand Down

0 comments on commit f121f1a

Please sign in to comment.