Guides Guidelines

[hwhelchel]

What's missing from the TRIP Guides

We need a simple overview of the basics of contributing new or material edits to Guides here.

Expected content

Topics users might be interested in:

• The purpose of the guides
• Who can contribute to the guides
• What sort of contributions can be made to the guides
• How to contribute to the guides

Actual content

Right now this is a stub page.

[hwhelchel]

@eugene-shvarts you had some good thoughts around some writing that needs care and consideration of public perception. When you have a moment, share more about what you're thinking those guidelines should be here.

[eugene-shvarts]

@hwhelchel

• Keep added material current, rather than future-facing
• Only make true statements consistent with our internal understanding of how our system works, and what is necessary and appropriate to inform the public about
• If unsure about language/topic/whether a feature is ready, ask the relevant people early and often. Otherwise it's all up to you

Those are the main ones on my mind, what do you think?

[hwhelchel]

@eugene-shvarts love these suggestions. @enki how does this look to you?

If it looks good to Paul, Eugene would you be game to create a change request for this?

[hwhelchel]

I propose we also add a guideline that no meaningful change request is accepted without a related issue here in GitHub.

A meaningful change request is anything beyond fixing grammar or factual inaccuracies.

[hwhelchel]

• Organize guides around roles people can play on the network rather than around product or tech surfaces.
• If there is a section around a product or tech surface (e.g. The TRIP Report newsletter) structure it around how community members can contribute to that. If they can't contribute to it, remove or reorganize the section.

(In fact, maybe The TRIP Report section could be reworked into a role that people identify with instead.)

[hwhelchel]

More points to add to this guide:

• Avoid conjunctions
• Use second person
• Add list of naming conventions / word choices and reasoning
• Guide title convention
• Markdown formatting
• Consistent punctuation and capitalization
• Use Hemingway App to make copy more readable
• Unordered/ordered lists / indenting
• Spelling and grammar check
• Show don't tell (project development not writing style)
• Use "invite" language instead of "referral" language
• 1/3/1 sentence structure and other variations (1 sentence paragraph, 3 sentence paragraph, 1 sentence paragraph)
• Use "onchain" instead of "web3", "crypto", or "blockchain".

Todo: add notes from Eugene CR.