FAQ Styleguide

--- tags: meta title: FAQ Styleguide description: A style guide for our FAQ --- # FAQ Guidelines :vertical_traffic_light: This document should serve as a standard guideline on how to write an FAQ for r/IndiaInvestments wiki. There's no _one true_ way of writing it. But when working on a collaborative project such as this, we all should agree with certain ground rules, to have uniform content throughout our knowledge base. Following points are meant as a way to help you form an article from scratch. We can then tweak it later, based on review feedback. --- ### 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. --- ### 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. An FAQ is not the place to start churning out academic dissertations. --- ### Be unbiased :yin_yang: A good rule of thumb is to ask yourself this: _if someone reads this 5 years from now, how much change would this text need to remain relevant?_ Focus on producing _evergreen_ content. For example, you might be tempted to write _Product X is not right for you, it doesn't even have feature Y_. Except, five years from now, it might. Or, maybe this feature Y isn't needed five years down the line. A better sentence would be _At the time of writing this, product X doesn't support Y. You may consider it if that changes_. Avoid opinions. It's okay to say _historically equity has beaten inflation over the long term, at least in the last 40 years._ But it's not okay to phrase it as _equity is the only asset that'd perform better than inflation_. No one can predict that. ### 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: - Keep the question in mind, when "answering" the FAQ. Any off-topic content, that does anything but directly answer the query, doesn't belong in that FAQ. - Avoid referring to yourself in first person. _I_, _me_, _we_, _present author_ etc. pronouns / phrases are best avoided. - 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 both wiki and FAQ, that we'd be able to refer FAQ readers to relevant wiki articles. This also creates a better experience through _self-segmenting_ users. - 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 an FAQ, read it yourself, before you ask others to review it. That alone would help you catch common errors or issues with it, before others even need to review it.