feat: Update Contributing guidelines for writers

[ADubhlaoich]

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.

• I have read the contributing guidelines
• I have signed the F5 Contributor License Agreement (CLA)
• I have rebased my branch onto main
• I have ensured my PR is targeting the main branch and pulling from my branch from my own fork
• I have ensured that the commit messages adhere to Conventional Commits
• I have ensured that documentation content adheres to the style guide
• If the change involves potentially sensitive changes¹, I have assessed the possible impact
• If applicable, I have added tests that prove my fix is effective or that my feature works
• I have ensured that existing tests pass after adding my changes
• If applicable, I have updated README.md and CHANGELOG.md

Footnotes

1. 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. ↩

[ADubhlaoich]

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.

[mjang]

This feels like TMI

[ADubhlaoich]

What would a more concise version of this look like? It's admittedly slightly redundant with the guidance in the new section.

[mjang]

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.

[mjang]

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.

[ADubhlaoich]

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.

[ADubhlaoich]

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.

[jputrino]

I don't think we want to instruct contributors to use <hr>s to visually break up sections. This is something that should be handled by the theme.

[github-actions]

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/docs/428/

---

[mjang]

While I won't stop this change, it feels like we're now writing CONTRIBUTING_DOCS.md for the developer.

[mjang]

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?

[mjang]

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.

[ADubhlaoich]

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.

[mjang]

In that case,

Suggested change

	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.

[mjang]

Our audience is not "mostly writers": it is mostly engineers, both as readers and actual (Internal) contributors.

I disagree. That's one reason why I split out CONTRIBUTING_DOCS.md from CONTRIBUTING.md

[mjang]

@ADubhlaoich These files are focused on external contributors. With the possible exception of CS students, none of them have been engineers.

People from F5/NGINX fall into a different category. That's why I have the F5-NGINX-team* files. If you want to create a new file for such users, that's literally a different story.

Part of our strategy with this repository is to make documentation accessible even to people who don't know Git. The changes in this PR, as currently written, would deviate from this strategy.

I'm therefore going to reject this PR, unless told otherwise, or until I hear more about why you're pushing this change on the community. Tip: I know of documentation repositories that work for more technical users, such as GitLab. In that case, companies contribute entire features to a product, including documentation. I'd love to see that as part of a long-term strategy.

[ADubhlaoich]

I think a lot of the disagreement here comes from different design intent for this file.

I strongly believe this document should focus on instructing people on how to use Hugo. In that focus, it is currently outdated.

I don't believe this document should or currently focuses on how to write content: that feels closer to the remit of the style guide.

[jputrino]

I think we need to start up a Discussion thread on the intent for the file; information like this informs our approach to managing content in this repository, so it should be done in the public forum as opposed to in the context of a PR that will be buried in the git commit history.

I think Alan's approach here -- to mention the tools we use and link out to where readers can find more information if they're unfamiliar with the topic -- is inline with how we approach documenting our products.

The content itself is relevant and accurate, so I'm a 👍🏻 on the changes.

[mjang]

The content itself is relevant and accurate, so I'm a 👍🏻 on the changes.

In that case, I withdraw my block.

[mjang]

Why are we leaving out the other templates?

[ADubhlaoich]

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.

[mjang]

Suggested change

	Our archetypes [currently include](/archetypes/) the following:
	Our templates [currently include](/archetypes/) the following:

[mjang]

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 ?

[ADubhlaoich]

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.

[jputrino]

This is also something that we should resolve in the context of a discussion, so we can more easily refer back to it later. I'm leaning toward updating the archetypes and removing the template files, but I think we should come to an agreement about the best approach as a team and then act.

[mjang]

This feels like TMI

[mjang]

Suggested change

	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.

[mjang]

Suggested change

	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:

[mjang]

This sounds like a style guide discussion. Have we decided to use backquotes sparingly?

[ADubhlaoich]

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 foo output:

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.

[JTorreG]

We have discussed in the past, to great extent, to avoid using inline code for things that are not code.

[mjang]

Our audience is not "mostly writers": it is mostly engineers, both as readers and actual (Internal) contributors.

I disagree. That's one reason why I split out CONTRIBUTING_DOCS.md from CONTRIBUTING.md

[mjang]

@ADubhlaoich These files are focused on external contributors. With the possible exception of CS students, none of them have been engineers.

People from F5/NGINX fall into a different category. That's why I have the F5-NGINX-team* files. If you want to create a new file for such users, that's literally a different story.

Part of our strategy with this repository is to make documentation accessible even to people who don't know Git. The changes in this PR, as currently written, would deviate from this strategy.

I'm therefore going to reject this PR, unless told otherwise, or until I hear more about why you're pushing this change on the community. Tip: I know of documentation repositories that work for more technical users, such as GitLab. In that case, companies contribute entire features to a product, including documentation. I'd love to see that as part of a long-term strategy.

[javorszky]

Hi, engineer on the NIC team here. I would very much love it if I, and other engineers, were also regarded as a target audience for this document. Part of our workflow is creating the features and the documentation for said features. In my view the less work the docs team needs to do on any doc changes, the better, but that can only happen if we, the engineers, know what to do in the first place 🙂

I also like overexplaining things. I'd rather that than having to open several new tabs to figure out what's what.

Though it doesn't matter, I do call them backticks.

[mjang]

Hi, engineer on the NIC team here. I would very much love it if I, and other engineers, were also regarded as a target audience for this document. Part of our workflow is creating the features and the documentation for said features. In my view the less work the docs team needs to do on any doc changes, the better, but that can only happen if we, the engineers, know what to do in the first place 🙂

I also like overexplaining things. I'd rather that than having to open several new tabs to figure out what's what.

Though it doesn't matter, I do call them backticks.

Hi @javorszky , I appreciate your perspective, and your efforts to create documentation for NIC. It's helpful, and I appreciate your work.

One of the reasons we created this open source repository is to appeal to less technical users. Today, we have contributions from both technical and less technical users. Most of the technical users are from within NGINX and F5. Since we have two audiences, I did suggest that we have F5-NGINX-* files for those of us from NGINX and F5.