diff --git a/doc/style-guide.md b/doc/style-guide.md new file mode 100644 index 0000000..e700b52 --- /dev/null +++ b/doc/style-guide.md @@ -0,0 +1,32 @@ +# Style guide + +## Blog posts + +### Voice + +* Direct; writing should be succinct and to the point +* Personal and informal is OK up to a point + * For example, avoid opening a blog post with "Knock knock. Who's there? It's me, + Matt, and ..." + * Talking about my passions, hobbies, sense of humor, learning style, etc. is fine. + Using some limited slang is probably fine, but consider inclusiveness (English may + not be every readers' first language, and slang dialect is an unnecessary layer of + obfuscation). +* Use emoji liberally in headings; very conservatively in prose. + * Emojis at the beginning of the heading, not at the end. + * If positioning an emoji in the middle of the heading, there should be a really + good reason. + + +### Structure + +* Short sections broken up in to little subsections, each with headings/subheadings. +* Short paragraphs. + + +#### General format + +* Recap/TLDR: Summarize everything! Spoil the solution. +* Introduction: Sets up a problem. +* Body: Describes a solution in detail. +* Conclusion: Wrap-up, why you should do this.