proposed changes to files for Reference template #192
Conversation
aidanatwork
added
the
template-reference
|
Question (non-blocking): I'm not sure the base template has fully settled yet, considering we're going to be holding a series of workshops on it for the next few weeks. What are your thoughts on that, @aidanatwork ? |
|
Most of the changes are just improvements to the copy. I think as the base template changes, I’m happy to submit further updates to the reference template. My aim partly was to kick the tires of the base template as I updated reference. I have extensive notes taken during the process that I’ll share during the workshop.
…Sent from my iPhone
On Mar 17, 2021, at 7:37 AM, Alyssa Rock ***@***.***> wrote:
Question (non-blocking): I'm not sure the base template has fully settled yet, considering we're going to be holding a series of workshops on it for the next few weeks. What are your thoughts on that?
—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub, or unsubscribe.
|
|
@aidanatwork , sounds good. I'll review the PR with that in mind, then. :) |
There was a problem hiding this comment.
General comment: Great work on this! There's a lot to like here and I have only minor wording fixes.
Suggestion (non-blocking): I do have one general comment about this template that I wonder if you want to work into the introduction to the About guide. My new employer has required me to read and follow the guidelines in Developing Quality Technical Information by IBM. This book is about a philosophy called "progressive disclosure" that strongly advocates for making UIs self-documenting as much as possible using tooltips and other UI guidance. The goal is to cut down on the amount of reference documentation you need to write and to avoid bloated over-documentation, especially for reference material where the function of fields are fairly obvious. I don't know if you want to mention that as a caveat in this template, e.g. decisions about when to use it and when not to use it?
If this is out of scope for your PR and you don't want to deal with that, we can just spin my idea off as a separate issue. Just a suggestion.
|
|
||
| ### The Body section | ||
|
|
||
| The structure of reference articles vary based on the factual information you are documenting. | ||
| The structure of reference articles varies based on what kind of information you are documenting. Formats that permit structured presentation of entries are best: tables, lists, interactive object-schemas, etc. | ||
| In most cases, reference information is easiest to express as a table. |
There was a problem hiding this comment.
Praise: Love this line you've added. Awesome!
| ## Overview | ||
| {Document author tip: | ||
| Summarise what this reference article is about. Explain what all the entries defined on the page have in common. What you put here is reused in the Overview section of your doc site and included in HTML description tags. For help with writing and structuring a reference article, see the file about-reference.md in this directory. Check out https://www.markdownguide.org/basic-syntax/ if you need help with markdown syntax. | ||
| } |
There was a problem hiding this comment.
Question (non-blocking): Is British English the adopted standard of for GDP? Honestly wondering out loud here. If so, have we added that to our contributing guide yet?
There was a problem hiding this comment.
No, I'm pretty sure we are using American English. So summarise is a typo.
There was a problem hiding this comment.
Sounds good. You can resolve this comment when it's fixed. FYI, I noticed it in line 16 as well.
| ## Overview | ||
| {Document author tip: | ||
| Summarise what this reference article is about. Explain what all the entries defined on the page have in common. What you put here is reused in the Overview section of your doc site and included in HTML description tags. For help with writing and structuring a reference article, see the file about-reference.md in this directory. Check out https://www.markdownguide.org/basic-syntax/ if you need help with markdown syntax. | ||
| } |
There was a problem hiding this comment.
Sounds good. You can resolve this comment when it's fixed. FYI, I noticed it in line 16 as well.
aidanatwork
deleted the
reference-template-aidans-proposed-changes-031521
branch
Purpose / why
These files need to be edited to better match the new base template, and can be improved in other ways. Fixes this issue: #191
What changes were made?
Removed front-matter that is no longer needed. Made explicit use of "document author tips", improved the copy, made clear that tables are examples and not part of the required template structure itself, added prompt to example file explaining what needs to be put there in a future PR. Note that file names were not changed to match base template format, as I plan to propose changes to that naming scheme.
Verification
Compare this file to the base template and the previous version, and decide if the new one is an improvement and properly uses the base template.
Checklist