How To Styleguide

--- tags: meta title: How To Styleguide description: A style guide for content creators, for How To section --- # Styleguide : How To Section :vertical_traffic_light: 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 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 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. --- ### Tone :musical_note: It should have a balanced tone. No need to be overly aggressive / abusive / cocky / snarky. Simultaneously, avoid being overly cute or too nice. Basically, avoid emotional hot-takes, or controiversial flame-baits. Standard text, with somewhat firmness is well suited. Write less. Break complex sentences down to simpler ones. Use periods more than conjuctions. Avoid phrases like _in my humble opinion_ (you're writing it, of course it's in your opinion. Duh!), or _correct me if I'm wrong_, or _I'm no lawyer_. Similarly, avoid raining emojis. Furnish information that you can, and avoid taking the note in a direction that you're not comfortable with. In particular, avoid passive mode wherever possible. Sure, it's not always avoidable - sometimes a sentence may even have no other choice but to omit the subject. But for most scenarios, active voice is better suited. A _how to_ is a step-by-step guide - your language should be instructional. _Do X_, _Once X is done, do Y_, _If X didn't work, do Z_ - these are fine. Use buller points / ordere lists as much as possible. --- ### Wall of text 🧱 Reading large wall of text can be unsettling, and boring. Strive to not have pargraphs more than 1-2 sentences long. If you're writing a paragraph that's more than three sentences long, you're doing something wrong. A _how-to_ document is not the place to start churning out academic dissertations. Most importantly, the general structure of a _how-to_ document is a list of tasks to execute; which easily lends itself to avoiding long running paragraphs. --- ### Be unbiased and factual :yin_yang: How-to articles can get out of date, but that's ok. You should use images (both dark & light mode), videos etc.; or even simple diagram (use Excalidraw if needed) to draw some flowcharts / gantt-charts etc. Make sure user has the right information, without assuming anything extra about the user. For example, if the question is _how to open a bank account in India_, don't start with the assumption the person is a resident Indian, living in India. They might be NRI / PIO, or sea-farer. It's ok to clearly call that out in your writing. That you're writing the process, for a subset of users, and what defines that subset of users. ### Linking to external resources :globe_with_meridians: In course of creating a content, you'd be tempted to link to an external resource - some blog post, news articles, videos, other community posts from Reddit / Valuepickr / TradingQnA etc. Don't. At least not directly to that resource. Links can be taken down / removed / made inaccessible. As much as possible, from the beginning, we've taken steps to not let that happen. Ideally, we'd want to link to Internet Archive's archived version of that link. Here's how a sample link to CNN's coverage of Buffet's Annual Shareholder letter of 2021 might look like: [Real Link](https://edition.cnn.com/2021/02/27/investing/warren-buffett-annual-letter/index.html) | [archive.org link](https://web.archive.org/web/20210301184753/https://edition.cnn.com/2021/02/27/investing/warren-buffett-annual-letter/index.html) | [archive.is link](https://archive.is/nnPAV). You could use Internet Archive's Wayback machine to search for a latest archived version yourself. Alternatively, you could use these extensions / plugins in your browsers, to get the archived versions: - [Firefox Web Archive](https://addons.mozilla.org/en-US/firefox/addon/view-page-archive/) - [Chrome Web Archives](https://chrome.google.com/webstore/detail/web-archives/hkligngkgcpcolhcnkgccglchdafcnao) --- ### Miscellaneous :butterfly: - Don't write detailed stuff like a research paper or a due diligence. Some reasoning is ok, but FAQ is not a chapter in wiki. Brevity is desired. Eventually, we'd have enough content in our wiki and _How To_ sections, that we'd be able to refer _How To_ readers to relevant wiki articles, for detailed take on the matter. This also creates a better experience through _self-segmenting_ users. - Be careful with personal information To write a _how to_ entry, you might end up taking screenshots or screenrecordings, with your personal details present. Would highly recommend hiding those info out, or altering them using browser dev-tools, if needed. It's ok if you don't know how to do that; we can help with that if you are not comfortable with adding those screenshots / screen-recordings yourself. - No plagiarism If you have read an online article or blog post whose content you wish to use, read & understand it first; then write in your own language. Also credit the original source. You can quote a source, as long as you cite it properly. But copy-pasting verbatim from a source and trying to pass it off as your own work would invite troubles for you. We do this check before inserting every piece of content into the wiki. And it's surprisingly easy to discover when someone copies even a single paragraph from external sources. - After writing a _How-To_, read it yourself, before you ask others to review it. That alone would help you catch common errors (grammar, spelling) or issues with it, before others even need to review it.