RFC: Naming guides

[colebemis]

Problem

As I've been writing documentation guides for Doctcat, I've noticed that the way we've named the guides is slightly inconsistent. Here's how the navigation is currently structured:

- Getting started
- Guides
  - Gatsby CLI
  - Side navigation
  - Adding a hero
  - Creating live previews
  - Changing the favicon
  - Deployment
- Theme options
- Components
- Contributing

Some guides start with a present participle (e.g. "Changing the favicon," "Creating live previews") and some don't (e.g. "Gatsby CLI," "Deployment"). I think now is a good time to discuss some guidelines around naming guides and navigation links in general.

Questions

• What should we name the Doctocat guides? Is it okay to use a present participle in some guide titles and not in others?
• More generally, how should we organize the navigation? Do we need a "Guides" category? Should the documents under "Guides" be reorganized?

Goal

The goal of this issue is to settle on an structure for the side navigation of the Doctocat documentation site that is consistent and clear.

References

Here are a few documentation sites I've used as "inspiration:"

• https://gatsbyjs.org/docs
• https://mdxjs.com
• https://theme-ui.com
• https://styled-system.com
• https://gatsby-theme-carbon.now.sh
• https://help.github.com/en

[shawnbot]

Thanks for opening this, @colebemis! @ashygee suggested that we ask for @stephbwills' input, as GitHub's content style guide don't yet have any specific guidance on how we should name the navigational links.

When I think about these things I channel my former colleagues from 18F, whose own content guide has a lot in common with ours. Here's the part that jumped out for me from the section on technical and interface writing:

Be consistent with how you phrase titles. If your guide or tutorial has several pages, stick to the same naming convention for scannability, such as:

Nouns: Policies, Teams, Offices Verbs: Create an account, File a report, Download our data

Use sentence case for headings.

Given that we use the phrases "getting started" and "contributing" so frequently, I think that tense makes sense to use elsewhere—but sparingly! I would suggest something more like the following for side navigation:

• Getting started
  • Use the Gatsby CLI
  • Contributing
• Theme options
  • Navigation
  • Hero image
  • Favicon
• Writing content¹
• Deployment
• Components
  • Code examples
  • Side navigation
  • Site header

But I'd also love to hear from the rest of @primer/ds-core team if anyone has strong opinions!

¹ "Writing content" obviously doesn't exist yet, but I would suggest that we have a page that, at the very least, describes our Markdown + MDX configuration.

[colebemis]

What if we consolidated and flattened the navigation into something like this?

• Getting started
  • Gatsby CLI
• Customization¹
• Writing MDX²
• Live code
• Deployment
• Theme options³
• Components⁴
• Contributing

¹ As @shawnbot, @ashygee and I discussed, "Customization" page would be the consolidation of "Changing the favicon," "Adding a hero," and "Update the side navigation."

² @shawnbot I like the idea of included a brief overview of how to write MDX. We could do something similar to Docz's "Writing MDX" page.

³ I think "Theme options" should be quick reference for the theme configuration options that can be set in gatsby-config.js. We can go into more detail about ways to configure the theme in the "Customization" section.

⁴ "Components" would be an API reference for all the components that Doctocat exports from index.js similar to what we do on https://primer.style/components.

[colebemis]

@shawnbot What if we moved Theme options into the Customization page?

[shawnbot]

@shawnbot What if we moved Theme options into the Customization page?

I think that makes a ton of sense!

[colebemis]

Cool. Working on a pull for these changes right now 👍