Skip to content

Add content guidelines

Warren Gifford requested to merge content-guidelines into main

Created by: quinnkeast

This PR implements more comprehensive content guidelines that replace the style guide.

It adds these pages (along with the "Content guidelines" page):

  • Voice and tone
  • Actionable language
  • Style & mechanics
  • Word list

The path to view locally is: /handbook/communication/content_guidelines.

I've moved the majority of content from the previous style guide into the content in the new pages in the most logical places, so nothing's lost along the way.

All of the examples reflect real or potentially-real content that would be found in Sourcegraph. As well, all of the guidelines reflect and then extend upon the current styleguide. There's one section that's still todo: the voice attributes in Voice and tone.

To make it as easy as possible to use, I've added some new styles to the handbook to support the "usage" element specifically for these guidelines. Unfortunately, this means there's some gnarly HTML in the markdown, like:

<div class="usage">
<div class="item yes">
<h5>Yes</h5>
<ul>
<li>Create a new campaign</li>
<li>Save your changes</li>
</ul>
</div>
<div class="item no">
<h5>When necessary</h5>
<ul>
<li>Create campaign</li>
<li>Save changes</li>
</ul>
</div>
</div>

Three things about this:

  • I wasn't sure whether HTML in markdown should be indented properly, so I left it unintended (painful as it is) with the idea it'll be easy to change if it'd be better to follow convention.
  • Because of the HTML, it's much easier to preview while running locally than in the diff.
  • I'd love if there were a solution that was just markdown instead of HTML. Happy to make changes!

Next steps:

  • If this PR is approved, then we'll likely need to replace and redirect the current Style guide page with the Content guidelines page.

Merge request reports

Loading