RFC: Naming guides about doctocat HOT 5 CLOSED

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.

from doctocat.

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.

from doctocat.

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

from doctocat.

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

I think that makes a ton of sense!

from doctocat.

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

from doctocat.