docs icon indicating copy to clipboard operation
docs copied to clipboard

Style guide: add items from style guide questions doc and improve the structure

Open andrew-walford-prisma opened this issue 2 years ago • 0 comments

Bring in the items in our style guide questions doc. Tana has commented on most, and I can make judgment calls on the others.

Some are TBD, pending agreement with Michelle.

This PR also includes the restructuring work: Improve the structure.

Tana wants us to use the RackSpace style guide as a basis. We can use similar sections to that.

We might want to split our guide up into logical pages. My thinking is:

  • Writing style sections - tone of voice, word choice, grammar, formatting guidelines - these can go on one page, and indeed we might sometimes want to search within this content
  • Terminology (what terms to use, what capitalization and formatting) - this is a page I can see us going to a lot, and command-F-ing
  • Image and diagram guidelines - useful when preparing a diagram or image - referred to less frequently
  • Content type guidelines - e.g. procedural, reference, API reference - useful when you’re new to the docs, less useful for writers accustomed to our guidelines

These will not be the actual page names - it's just an indication of what will be on each page

andrew-walford-prisma avatar Jun 30 '22 08:06 andrew-walford-prisma