[NEW CONTENT] Define and document standards and styles for IPFS docs

[johnnymatthews]

Note: This issue was opened as a result of the November 2019 close-reading audit captured in ipfs-inactive/docs#326.

One consequence of having several different writers create documentation is that there isn't any consistency between the pages in terms of writing style, word choice, styling, and examples. To create a consistent experience across all IPFS documentation we should:

1. Create a personality and writing style for our docs. Note: "personality" of the voice in our docs is a separate effort from the "user personae" we discuss when we're talking about general docs user research.
2. Create contribution guidelines -- these should be presented alongside the IPFS developer contributor guidelines, as well as in our own docs site
3. Create a style guide for writing docs.
4. Create a code persona and base example project to pull code-blocks and small examples from.

Strikethroughs denote completed tasks.

Let's use this issue as a holding pen for the four efforts noted above, but manage and track each effort in its own issue.

[johnnymatthews]

This contribution guide is probably best as a one-pager covering the following topics:

Content Guidelines

• Style
• Tone
• Grammar

How to Contribute

• Types of Contribution:
  • Fixes
  • New Articles or Pages
• File an Issue
• Create a PR
• Discuss

Tools and Workflow

• VSCode Extensions
• Grammar and Spelling

[johnnymatthews]

This issue has been partially addressed by b2e0438cecea3c089ddd43d54275a0d3b77690e1. Just need to finish up the code persona.

[jessicaschilling]

@johnnymatthews Awesome! Just please be sure to update any changes in the beta as well. Thanks!

[johnnymatthews]

Merged into ipfs/docs master: 173d0d1. Also Copied into ipfs/ipfs-docs-v2.

[jessicaschilling]

Some follow-up ...

• Where is this page being linked to nav-wise in both the legacy and the docs beta?
• Are there deep links within the docs content that should link out to this page?
• Can you please add a link to this page in the main ipfs dev contributor guidelines (probably with some guidance on why writing good documentation is important)? https://github.com/ipfs/community/blob/master/CONTRIBUTING.md
• Can you please incorporate anything useful from this document, then deprecate it with a "this document lives here now" message in it? https://github.com/ipfs/community/blob/master/DOCS_STYLEGUIDE.md

[jessicaschilling]

@johnnymatthews -- per our meeting today, can you please make sure that consideration of personae and a link to our persona guide be included in your materials? Thanks!

[johnnymatthews]

This issue is being addressed in the docs-contribution-section branch of the ipfs/ipfs-docs-v2 repo.

[johnnymatthews]

Finally got around to creating the code-persona. Still need to flesh out the examples, however I'm happy with this very basic code persona for now. Creating a full code persona will be a much larger project than when I first drafted out this issue. IPFS is much more complex and has far more moving parts than I originally thought.