Base template - draft #2 #14
Conversation
Testing instance.
…ect/incubator into edits1-lbrindley
Base Template - Draft1
Draft 1 of Base Template content
Updating for Draft 2 of 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. |
There was a problem hiding this comment.
Maybe start with something like:
The base captures the structure and common elements that all doc type templates associated with The Good Docs Project should follow. It includes guidance for downstream template authors to follow when creating a new template.
Note: I think we should call out "template author" as the target audience.
| @@ -2,20 +2,120 @@ | |||
| <!-- Describe the title of your article by replacing "Base Template" with the page name you want to publish to. --> | |||
There was a problem hiding this comment.
We shouldn't be making use of HTML comments because they don't get rendered in github and some readers won't find these comments. I suggest follow the convention we started within the Style Guide and use {Brackets for Variables} and instructions to the author.
There was a problem hiding this comment.
This was just in the original source code of the markdown page, it's not needed, I shall delete it.
|
|
||
| ## Before you start | ||
| To be able to make the best of this base template, you should have sufficient knowledge of: | ||
| <ol> |
There was a problem hiding this comment.
Could you please convert this to markdown format instead of HTML
There was a problem hiding this comment.
I thought this was markdown! :) I was just trying to get at a numbered list, will try to see if there are alternate ways of doing it in markdown.
| ## 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. |
There was a problem hiding this comment.
At the base template level, I'm inclined not to call out the lower level templates. But if we are, I think there is probably only three, not four templates to call out:
- Procedural, or step-wise, or ... (not sure what the right word is here)
- Reference
- Explanation
I'd also be inclined to put this explanation in the "About" page.
There was a problem hiding this comment.
I'd use concept, task, and reference.
There was a problem hiding this comment.
Right, I'll re-work on this section. Thank you @camerons and @Loquacity for the suggestions.
| 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. |
There was a problem hiding this comment.
I'd delete this sentence.
If people are following The Good Docs Project processes, then we are expecting them to follow our base template guidance.
There was a problem hiding this comment.
Meaning? Sorry, I didn't understand this. What I'm trying to say here is, "when" you are likely to need the Base template. As in, how would you know you need the base template?
|
|
||
| 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. |
There was a problem hiding this comment.
This is selling to case for writing templates, which is a good case to make, but I think we are missing our target audience. I feel our target audience are template authors, who have already decided they need to create a template.
Our job now is to help them to make the template consistent with the best practices we are defining.
I'd suggest trim this section by 50% or more.
|
|
||
| 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) |
There was a problem hiding this comment.
The base template is for doc type template authors who wish to align and/or contribute to The Good Docs Project.
|
|
||
| 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 |
There was a problem hiding this comment.
I personally try to avoid using acronyms such as "GDP", especially for new users, as it slows their comprehension.
If you do use GDP, it should be "the GDP".
There was a problem hiding this comment.
Noted. Will correct accordingly.
|
|
||
| ### 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 |
There was a problem hiding this comment.
For most/all your lists in the doc, I feel you should have a period at the end.
Google's style guide is ambiguous in their requirements here, but it is fairly clear in Microsoft's guide:
https://docs.microsoft.com/en-us/style-guide/scannable-content/lists#punctuation
In bulleted and numbered lists, end each list item with a period if:
- Any item forms a complete sentence when combined with the list introduction that precedes the colon. ...
There was a problem hiding this comment.
Noted, and shall be corrected. Thanks for the style guide reference.
| <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 |
There was a problem hiding this comment.
I'd be inclined to suggest that we shouldn't create example templates.
Reason being is that the best examples we have are our existing templates (which hopefully will be updated to follow our base template).
| <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> |
There was a problem hiding this comment.
Numbered lists work like this:
| <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. | |
| 1. Writing technical documentation - to accurately and clearly express instructions to the reader. |
But I would argue that being only two steps long doesn't make it long enough for a numbered list, it should probably be paras 😉
|
@viraji I've removed the Contributors' Guide from this PR, and fixed all the merge conflicts for you. You can review the Contributors' Guide stuff in thegooddocsproject/templates#172 if you're interested. This PR is getting pretty hefty (19 commits!), so it might be time to merge this one into master and start a new one focusing on reviews. |
|
Noted @Loquacity - thanks for all the help. |
Incorporating review comments of PR #14.
Editing as per review comments from #14.
Incorporating review comments of PR thegooddocsproject/incubator#14.
Editing as per review comments from thegooddocsproject/incubator#14.
Incorporating review comments of PR thegooddocsproject/incubator#14.
Editing as per review comments from thegooddocsproject/incubator#14.
What changes were made?
Please check: