Guides Guidelines
This guide documents guidelines for writing TRIP Guides.
This guide follows itself acting itself as an example of how to write a TRIP Guide.
After reading this guide, you will know:
What conventions to follow when writing TRIP Guides content.
Prologue
Each guide should start with motivational text at the top (that's the little introduction in the blue area). The prologue should tell the reader what the guide is about, and what they will learn.
In GitBook these are called Hints.
Show Don't Tell
"Showing" is stating how TRIP works today. "Telling" is stating how TRIP will work in the future.
Readers want to understand how TRIP works at this moment in time. If we incorporate content about how TRIP can or should work in the future, it creates opportunity for confusion.
Therefore show don't tell when writing TRIP Guides content.
Roles over Technology
Organize guides around roles users can play and actions users can take within the TRIP protocol rather than around product or tech surfaces.
Words to Avoid
Coinbase has done a lot of consumer research and "onchain" outperforms every other word that people use for crypto.
Therefore avoid using blockchain, web3, crypto, NFT, etc. where possible. Words like blockchain and NFT are ok to use where technical implementation details must be discussed. That said, consider if that content can be reworked to not reference them.
For example, refer to "digital collectibles" instead of NFTs.
Footer
At the end of each guide include a Hint section like this:
Feedback
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our Contributing to TRIP section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing content by creating a free account in GitBook. Check the TRIP Guides Guidelines for style and conventions.
If for whatever reason you spot something to improve but cannot do it yourself, please open an issue.
And last but not least, any kind of discussion regarding TRIP documentation is very welcome in the official TRIP Community on Telegram.
Headings
Use Heading 1 headings for guide sections. Use Heading 2 headings for guide subsections. Note that GitBook generates Heading 1 and Heading 2 headings as h2 and h3 in HTML respectively. That is ok.
When writing headings, capitalize all words except for prepositions, conjunctions, internal articles, and forms of the verb "to be":
Wording
Write simple, declarative sentences. Brevity is a plus. Get to the point.
Use the app Hemingway to help with this as well as assistants like ChatGPT or Claude.
Don't mindlessly copy and paste from them though or you're likely to make your writing worse.
Use present tense:
Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in TRIP Guides.
Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern TRIP usage.
Documentation has to be brief but comprehensive. Explore and document edge cases. What happens if a rider disputes a trip? What if a driver doesn't show up? What if a user doesn't have an onchain wallet?
Naming
The proper names of TRIP components have a space in between the words, like "Rideshare Server". All TRIP documentation should consistently refer to TRIP components by their proper names.
Spell rideshare, software, and onchain industry names correctly. When in doubt, please have a look at some authoritative source like their official documentation.
Pronouns
Write plainly and to the reader. It is ok to use "you"s and "your"s.
That said, when using pronouns in reference to a hypothetical person, such as "a user with a requested ride", gender neutral pronouns (they/their/them) should be used. Instead of:
he or she... use they.
him or her... use them.
his or her... use their.
his or hers... use theirs.
himself or herself... use themselves.
English
Please use American English (color, center, modularize, etc) spelling and correct grammar.
See a list of American and British English spelling differences here.
Oxford Comma
Please use the Oxford comma ("red, white, and blue", instead of "red, white and blue").
Examples
Choose meaningful examples that depict and cover the basics as well as interesting points or gotchas.
Feedback
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our Contributing to TRIP section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing content by creating a free account in GitBook. Check the TRIP Guides Guidelines for style and conventions.
If for whatever reason you spot something to improve but cannot do it yourself, please open an issue.
And last but not least, any kind of discussion regarding TRIP documentation is very welcome in the official TRIP Community on Telegram.
Last updated