feat: Update Contributing guidelines for writers #428
Conversation
This commit updates the CONTRIBUTING_DOCS.md file to our contemporary standards for documentation formatting, adding mention of Hugo archetypes and our ghcode shortcode, while also removing some slightly redundant information. Certain sentences have been removed or simplified to reduce the amount of contextual reading required: in certain cases, the reader is guided to refer to the style guide for more precise information, such as in the case of using images. There will likely be follow-up work in the future to more cleanly delineate guidance for using Hugo and guidance around writing content in a general sense, to tightly scope the purpose of this document in relation to the style guide.
github-actions
bot
added
the
process documentation
|
|
||
| We use backticks sparingly (\`\<some-text\>\`) for `monospace text`, typically for process names or commands. More information is available in the [Add code to documentation pages](#add-code-to-documentation-pages) guidance. | ||
|
|
||
| Sections can be separated with horizontal lines by using three dashes: `---`. |
There was a problem hiding this comment.
This is currently an option, but one we're likely to move away from in the future - CSS in the newer theme design uses whitespace for meaningful delineation between sections.
There was a problem hiding this comment.
What would a more concise version of this look like? It's admittedly slightly redundant with the guidance in the new section.
There was a problem hiding this comment.
One other thing that bothers me is the use of "backtick." I know it's a common term in coding, but we are focused on writers, and I think "backquote" is more accessible to a writer audience.
There was a problem hiding this comment.
Since we have the linked section, why even have these lines?
If this page is getting so long that we need links from the middle of a page to another part of the page, then maybe CONTRIBUTING_DOCS.md is getting too long.
There was a problem hiding this comment.
I don't actually think it's that long, but that reinforces the point you've made that including the lines is ultimately unnecessary. I'll get rid of it.
There was a problem hiding this comment.
I decided to use Google Trends to compare usage of the two terms: blue is backtick, red is backquote.
The sample size makes the trend functionally irrelevant IMO (That's measured in the hundreds, not thousands or millions): since our writers are largely engineers, I'm inclined to stick with it.
✅ Deploy Preview will be available once build job completes!
|
| @@ -143,7 +136,7 @@ You can also create custom callouts using the `call-out` shortcode `{{< call-out | |||
| {{<call-out "important side-callout" "JWT file required for upgrade" "fa fa-exclamation-triangle">}} | |||
| ``` | |||
|
|
|||
| By default, all custom callouts are included inline, unless you add `side-callout` which places the callout to the right of the content. | |||
| By default, all custom callouts are displayed inline, unless you add `side-callout` which places the callout to the right of the content. | |||
There was a problem hiding this comment.
Is there guidance on when to use in-line vs. out-dented callouts?
There was a problem hiding this comment.
No, and I actually have no knowledge of any instances when this has been used.
It feels like guidance on when to use one or another should probably be in the style guide as opposed to this document.
Just thought I'd change the word used since "include" has a certain semantic weight with our Hugo shortcode.
| @@ -158,24 +151,51 @@ Here are some other shortcodes: | |||
| - `readfile`: Include the content of another file in the current file, which can be in an arbitrary location. | |||
| - `bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}` | |||
|
|
|||
| ### Add code to documentation pages | |||
|
|
|||
| For command, binary and process names, you can use a pair of backticks (\`\<some-name\>\`): `<some-name>`. | |||
There was a problem hiding this comment.
| For command, binary and process names, you can use a pair of backticks (\`\<some-name\>\`): `<some-name>`. | |
| For command, binary, and process names, you can use a pair of backticks (\`\<some-name\>\`): `<some-name>`. |
There was a problem hiding this comment.
@travisamartin Was there meant to be change here?
There was a problem hiding this comment.
Oops -- I mean to add the serial comma. Fixed now.
| @@ -54,18 +53,27 @@ make clean - Removes the local `public` directory, which is the default | |||
|
|
|||
| ## Add new documentation | |||
|
|
|||
| We provide template files for different types of documentation. The templates, including instructions to use them and examples, are located in the [templates](templates) directory. | |||
| We use [Hugo archetypes](https://gohugo.io/content-management/archetypes/) to provide structure for new documentation pages. | |||
There was a problem hiding this comment.
This bothers me -- it's as if we're now relying on Hugo to provide templates -- and I'd expect to find templates at https://gohugo.io/content-management/archetypes/
As our audience is mostly writers, I think they'd struggle with the word "archtypes". Can you explain why you moved in this direction?
There was a problem hiding this comment.
If you insist on replacing "template" with "archetype," I'd like to see an explanation that's usable by TW-level users.
My personal acceptance criteria, if you go with this langugage: a typical TW should be able to understand the relationship between archetypes and templates.
There was a problem hiding this comment.
Archetype is the name of the Hugo implementation of a template. If you follow the link, this explanation is provided directly underneath the heading.
Our audience is not "mostly writers": it is mostly engineers, both as readers and actual (Internal) contributors.
These archetypes have been in use but not properly documented (The issue in the pull request description drove my original work on this PR): intent to convert the unused templates into Hugo archetypes has been discussed internally but not prioritized, which is why these changes include guidance on requesting one if desired.
There was a problem hiding this comment.
In that case,
| We use [Hugo archetypes](https://gohugo.io/content-management/archetypes/) to provide structure for new documentation pages. | |
| We provide templates. Hugo refers to templates as [archetypes](https://gohugo.io/content-management/archetypes/). They provide structure for new documentation pages. |
|
|
||
| `hugo new content <product/folder/filename.md> -k <archetype>` | ||
|
|
||
| Our archetypes [currently include](/archetypes/) the following: |
There was a problem hiding this comment.
Why are we leaving out the other templates?
There was a problem hiding this comment.
They have not been maintained or used. They might still be adapted for use in archetypes in the future, but all of that context seems like irrelevant noise. The templates themselves are still mentioned.
There was a problem hiding this comment.
| Our archetypes [currently include](/archetypes/) the following: | |
| Our templates [currently include](/archetypes/) the following: |
There was a problem hiding this comment.
They might still be adapted for use in archetypes in the future
Are you saying that we can't use these other templates with the hugo new content command? If so, should the PR also remove these files from https://github.com/nginx/documentation/tree/main/templates ?
There was a problem hiding this comment.
Are you saying that we can't use these other templates with the hugo new content command?
Basically, yeah. The templates do not interact in any meaningful way with Hugo archetypes.
There's a minimal amount of work needed to "convert" the templates into Hugo archetypes, but the bigger issue is that the templates were worked on in a vacuum and never adopted, whereas the archetypes were rewrites of templates to reflect the actual content IA patterns in production documentation.
I would personally like to remove the files, but it feels beyond the scope of the PR, though the fact nobody has interacted with them since creation means it's likely fine.
|
|
||
| We use backticks sparingly (\`\<some-text\>\`) for `monospace text`, typically for process names or commands. More information is available in the [Add code to documentation pages](#add-code-to-documentation-pages) guidance. | ||
|
|
||
| Sections can be separated with horizontal lines by using three dashes: `---`. |
Co-authored-by: Travis Martin <[email protected]>
| We provide template files for different types of documentation. The templates, including instructions to use them and examples, are located in the [templates](templates) directory. | ||
| We use [Hugo archetypes](https://gohugo.io/content-management/archetypes/) to provide structure for new documentation pages. | ||
|
|
||
| These archetypes include inline advice on Markdown formatting and our most common style guide conventions. |
There was a problem hiding this comment.
| These archetypes include inline advice on Markdown formatting and our most common style guide conventions. | |
| These templates (archetypes) include inline advice on Markdown formatting and our most common style guide conventions. |
|
|
||
| `hugo new content <product/folder/filename.md>` | ||
|
|
||
| This new page will be created with the default how-to archetype. To use a specific archetype, add the `-k` parameter and its name, such as: |
There was a problem hiding this comment.
| This new page will be created with the default how-to archetype. To use a specific archetype, add the `-k` parameter and its name, such as: | |
| This new page will be created with the default how-to template (archetype). To use a specific template, add the `-k` parameter and its name, such as: |
|
|
||
| Larger blocks of multi-line code text such as configuration files can be wrapped in triple backticks, with a language as a parameter for highlighted formatting. | ||
|
|
||
| You can also use the `ghcode` shortcode to embed a single file directly from GitHub: |
There was a problem hiding this comment.
The original issue didn't mention documenting this: I was the driver to get the shortcode in the first place, and I think I'm the only person who's been using it since it wasn't documented anywhere...
|
|
||
| Use the `img` shortcode to add images to documentation pages. It has the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). | ||
|
|
||
| 1. Add the image to the `/static/img` directory. |
There was a problem hiding this comment.
We include images in other directories as well (e.g. /static/nginx/images, /static/nginx-one/images, /static/nim)
- Maybe we should standardize
- But we should talk about it first
There was a problem hiding this comment.
I think a discussion of standardising the IA for all of our "peripheral" content would be beneficial, since we have already started to touch on it for how we organise includes.
| @@ -77,47 +85,32 @@ There are multiple ways to format text: for consistency and clarity, these are o | |||
| - Ordered lists: The 1 character followed by a stop - `1. Ordered list item`. | |||
|
|
|||
| > **Note**: The ordered notation automatically enumerates lists when built by Hugo. | |||
| Close every section with a horizontal line by using three dashes: `---`. | |||
|
|
|||
| We use backticks sparingly (\`\<some-text\>\`) for `monospace text`, typically for process names or commands. More information is available in the [Add code to documentation pages](#add-code-to-documentation-pages) guidance. | |||
There was a problem hiding this comment.
This sounds like a style guide discussion. Have we decided to use backquotes sparingly?
There was a problem hiding this comment.
I don't think this is properly documented in the style guide anywhere, but I've been hesitant to attempt to update the style guide due to pushback and deliberation in the past.
They're used somewhat sparingly in the sense that normal text can be used in context where we could refer directly to something like a process:
Use the following command to check the
foooutput:
Versus...
Use the following command to check the output of the Foo process:
The main offender for over-use in the past was in tables, where we made the decision to instead favour italicised text for parameters and values over monospaced text: it improved the readability considerably, and monospaced text would often break how tables were rendered.
I don't think that pattern/decision is recorded anywhere, but I could be wrong.
Proposed changes
This commit updates the CONTRIBUTING_DOCS.md file to our contemporary standards for documentation formatting, adding mention of Hugo archetypes and our ghcode shortcode, while also removing some slightly redundant information.
Certain sentences have been removed or simplified to reduce the amount of contextual reading required: in certain cases, the reader is guided to refer to the style guide for more precise information, such as in the case of using images.
There will likely be follow-up work in the future to more cleanly delineate guidance for using Hugo and guidance around writing content in a general sense, to tightly scope the purpose of this document in relation to the style guide.
Closes issue #164
Checklist
Before merging a pull request, run through this checklist and mark each as complete.
README.mdandCHANGELOG.mdFootnotes
Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to our style guide for guidance about placeholder content. ↩