How To Style Guide
A style guide for How To section of our wiki
We’ll soon have lot of process-oriented, step-by-step guides on various common tasks an investor needs to execute from time-to-time. These would form our How To section.
As a result, we’d have a ton of content that people can quickly refer to, as a sort of checklist.
But this has some challenges as well. Step-by-step guides can frequently become outdated, if the underlying product or platform changes in look-and-feel, functionality etc.
It could also be outdated simply because that process itself isn’t needed any more, or has been deprecated. This is why we need some risk management around this.
This document is for you, if you’re planning to warm-up with some contribution in the How-to section - either by writing, or by reviewing / guiding others.
Start with our general content guidelines, which also apply to How to section
Other than these, refer to following guidelines
- Optimize for anxiety and rush Someone might be reading a how-to guide, and be in a hurry to execute those steps. Respect their time. The document should clearly point out, and highlight through formatting (use emojis like ✅ or ❌); what should and should not be done. Point out known common issues. Don't leave out trivial details. Assume your how-to guide to be a run-book or field manual. Avoid description, focus on narration. A bullet-point ordered list is better, than a few paragraphs, in most cases. If you need to give detailed reasoning for a step, provide it in a way that if needed, user can easily skip that and move to next step.
- When writing about a product specific how to, it's best to directly link to how-to provided by the product itself. An entry for How to open a Zerodha account should have reference to Zerodha's own documentation and support articles on this. Add text beyond that, only if that adds value (maybe it points out common issues, or pitfalls) that's not already covered by those documentations.
- It's best if you clearly and explicitly mention pre-requisites for each how-to, and who all are not eligible / don't need to do this. An entry for How to file ITR 1, should clearly mention who are eligible for filing ITR 1, and how to confirm that.
Last modified 1yr ago