Merge pull request thegooddocsproject#14 from thegooddocsproject/vira…

…ji-incubator

Base template - draft thegooddocsproject#2

base-template/about-base-template.md

@@ -1,45 +1,63 @@
-# The Base Template
+# About Base Template
 
-## How do I create a new template?
+## Introduction
 
-Monotonectally engage orthogonal results vis-a-vis premier resources. Efficiently brand leveraged supply chains and interdependent best practices. Conveniently engineer resource-leveling opportunities without process-centric growth strategies. Appropriately implement intuitive materials without sticky scenarios. Rapidiously generate excellent channels before client-focused innovation.
+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.
 
-Synergistically optimize professional processes after goal-oriented information. Monotonectally leverage existing interdependent expertise before clicks-and-mortar portals. Continually parallel task visionary models before exceptional sources. Monotonectally procrastinate team building interfaces after team building "outside the box" thinking. Holisticly mesh cross-unit bandwidth with installed base methods of empowerment.
+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.
 
-Holisticly enhance optimal schemas rather than cost effective architectures. Authoritatively impact covalent schemas through go forward solutions. Proactively optimize B2C mindshare without flexible imperatives. Seamlessly visualize next-generation niches for world-class channels. Collaboratively whiteboard web-enabled outsourcing without exceptional markets.
+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.
 
-Dramatically innovate viral deliverables without next-generation solutions. Dramatically strategize goal-oriented opportunities and interdependent infomediaries. Synergistically orchestrate functional experiences whereas global services. Synergistically revolutionize wireless value after high standards in relationships. Professionally deliver end-to-end methodologies rather than principle-centered platforms.
+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.
 
-Objectively fabricate efficient deliverables and tactical human capital. Competently synthesize B2B systems vis-a-vis intuitive internal or "organic" sources. Synergistically orchestrate orthogonal markets rather than high-quality benefits. Credibly innovate user-centric infomediaries and strategic bandwidth. Holisticly generate economically sound value via process-centric infomediaries.
+The base template guides you through the steps to create a functional template that can be reused, adhered to, and followed consistently throughout.
 
-## Content of your template
+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. 
 
-### About the "Prerequisites" section
+## Prerequisites
 
-Professionally communicate high standards in total linkage via clicks-and-mortar relationships. Interactively predominate enabled metrics before distinctive best practices. Distinctively visualize parallel networks before cutting-edge partnerships. Uniquely synthesize multidisciplinary quality vectors rather than multidisciplinary scenarios. Conveniently drive team driven products through empowered alignments.
+To make the best use of this base template, you need a working knowledge of:
 
-### About the "Overview" section
+- GitHub to download, edit, and use the base template.
+- Markdown to create and edit the base template to suit your requirements.
+- Different documentation types to identify if you need to create a new template or edit an existing one.
+- Technical writing to produce a well-written document that includes the relevant reference aspects.
 
-Professionally redefine interactive deliverables whereas client-based e-commerce. Uniquely impact competitive quality vectors after resource-leveling content. Competently repurpose economically sound value before strategic processes. Competently benchmark global action items rather than user friendly internal or "organic" sources. Continually plagiarize flexible e-business after strategic core competencies.
+## Who will need the base template
 
-### About the content
+The base template is for:
 
-Energistically embrace worldwide applications without customized growth strategies. Energistically embrace orthogonal convergence vis-a-vis global internal or "organic" sources. Dramatically transform leading-edge networks rather than client-based convergence. Credibly revolutionize web-enabled interfaces before strategic solutions. Authoritatively incubate economically sound e-business with equity invested outsourcing.
+- Internal users - those who are already working in the Good Docs Project (GDP)
+- External users - the community outside of the GDP
 
-### About the "Reference" section
+Who want to:
 
-Professionally cultivate emerging alignments through multimedia based initiatives. Dramatically administrate cross-media users rather than cooperative paradigms. Synergistically redefine long-term high-impact niches via cross functional relationships. Authoritatively whiteboard interactive "outside the box" thinking with dynamic supply chains. Assertively pontificate standardized applications before goal-oriented sources.
+- Create new templates that do not yet exist within GDP
+- Edit existing templates that require changes
 
-### About the "Examples" section
+## How do you know you need the base template
 
-Synergistically redefine fully tested "outside the box" thinking before excellent customer service. Completely predominate functional methodologies vis-a-vis corporate core competencies. Energistically underwhelm dynamic supply chains through client-centric materials. Assertively negotiate client-based deliverables after timely infrastructures. Competently productize wireless ROI without customized mindshare.
+The base template is useful when:
 
-### About the "Glossary" section
+- 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 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
 
-Synergistically enhance multidisciplinary internal or "organic" sources whereas scalable quality vectors. Proactively productize team building scenarios without resource sucking alignments. Collaboratively syndicate market-driven vortals rather than market-driven catalysts for change. Quickly create team driven methods of empowerment vis-a-vis top-line metrics. Dramatically recaptiualize extensive opportunities rather than holistic ROI.
+## What will the base template cover
 
+The base template includes:
 
-## Further Reading
+- 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
 
-* If you are a first-time contributor to the Good Docs Project, read the Contributors' Guide
-* For more about the Information Architecture used within the Good Docs Project, read the Information Architecture Guide
+## Useful References
+
+- [List of existing GDP templates](https://github.com/thegooddocsproject/templates)
+- [Information Architecture guide](https://github.com/thegooddocsproject/incubator/tree/master/ia-guide)
+- [Glossary style guide](https://github.com/thegooddocsproject/glossaries)
+- [GDP governance](https://github.com/thegooddocsproject/governance)

base-template/base-template.md

@@ -2,20 +2,120 @@
 <!-- Describe the title of your article by replacing "Base Template" with the page name you want to publish to. -->
 # Base template
 
-## Prerequisites
-
 ## 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.
+
+
+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. 
+
+
+## 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>
+
+## 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>
+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>
+
+<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>
+
+<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>
 
-**Keywords:** Optionally add comma-separated keywords.
+<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>
 
-## Content 1
+<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>  
 
-### Subsection 1
+<li>Create the template that you are going to need, giving out step-by-step instructions, in clear, simple language. <br>
 
-## Content 2
+Although the specific template you are creating may vary, ensure that you have covered the basics of a good template. <br>
 
-## Reference
+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>
+
+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
 
-## Glossary
+- [About base template](https://github.com/thegooddocsproject/incubator/base-template/about-base-template.md)
+- [List of existing GDP templates](https://github.com/thegooddocsproject/templates)
+- [Glossary style guide](https://github.com/thegooddocsproject/glossaries)
+- [Contributor's guide](https://github.com/thegooddocsproject/templates/contributors-guide.md)