Contributor Guidance
Guidance and guidelines for contributing guides
Thanks for taking the time to contribute a guide to Relayable! Here you can find some guidance and guidelines to help you create a useful and high-quality guide.
We are a community-driven project, and we rely on the contributions of our users to create a comprehensive library of how-to guides. Your contributions are invaluable in helping us achieve this goal.
What makes a good guide?
A good guide is one that is clear, concise, and easy to follow. It should provide step-by-step instructions that are easy to understand, especially for someone who is not familiar with the topic or tech-minded.
Here are some tips to help you create a good guide:
1. Be clear and concise
Use simple language and avoid jargon. If you need to use technical terms, explain them clearly. Keep your sentences short and to the point.
Don't
Do
2. Ensure steps are easy to follow and comprehensive
Make sure each step is clear and easy to follow. Make sure to only include one action per step to avoid confusion.
Don't
Do
3. Start at the beginning
Begin with the most primitive step involved in the process (for example: 'Visit https://github.com'). Don't assume the user will know where to start the process or what the first steps are. Be thorough.
Don't
Do
4. Set up variables correctly
When creating a variable, please use lowercase text unless absolutely necessary. Avoid using spaces in variable names; instead use hyphen ('my-variable') or underscore ('my_variable') characters. If the variable can only represent a finite number of possible values, please mark the variable as an enum and provide these possible values as a comma-separated list. All variables must be used at least once in the steps of the guide.
Remember, these variables will be available to the developers using your guide, and the values they provide will be inserted into the guide for them to use.
Don't
Do
5. Enter full URLs
When entering URLs, please ensure you include the full URL, including the protocol (e.g., 'https://'). This will help avoid errors when users try to access resources.
Don't
Do
6. Enter named resources correctly
When entering named resources, please ensure you enter them between single quotes (e.g., 'My Account'). Also, please match the casing of the resource exactly as it appears in the platform application. This will help users to identify the resources they need to interact with. Also, do your best to describe where to find the named resource on the page, (e.g., "Click 'Settings' in the navigation panel.").
Don't
Do
7. Check over your guide before submitting
Once you've completed your guide, please review it carefully to ensure it is clear, with correct spelling and grammar. We will review all submitted guides, and will clean up any minor errors, but we ask that you do your best to ensure your guide is as polished as possible before submitting it to ensure a smooth review process.
A final note
That's it! If you follow these guidelines, and keep in mind that developers will use these to create their own bespoke guides for their non-technical clients to follow, you should be able to create a useful and high-quality guide.
Thanks so much for your contribution, and happy guiding!