Break up long sentences of continuous points for better readability. This can break up the presentation of densely packed information to make it more digestible. Example Instead of The three main classes of HTTP error status codes are 2xx indicating a successful response, 4xx for a user error and 5xx for a server error. Prefer The three main classes of HTTP error status codes are: 2xx indicating a successful response 4xx for a user error 5xx for a server error See for https://plainenglish.co.uk/punctuating-bulleted-lists.html for more examples

Designers apply whitespace to give their designs "a clean, uncluttered feel". We can apply the same principle in written documents. This does not just mean "break up into lots of paragraphs" - also consider: The spacing between a code block or image, and a block of text. Example Instead of Prefer The spacing between lines in lists Example Instead of Prefer Why? Good spacing aids readability, and can break up otherwise dense blocks of information. This helps to avoid overwhelming the reader.

In markdown, you can use single backticks (`) for inline code `like this`. This applies to things like: blocks of code stack traces names of libraries example variable names version ranges ...anything that may appear in a line of code! Markdown For whole blocks of code, you can use triple backticks (```): ``` like this! ``` For inline code snippets, you can use single backticks (`like this`): Google Docs In Google Docs, you'll have to manually apply a monospace font, such as Consolas. JIRA Use {code} for code blocks Use {{foo}} for inline text Why? Developers are used to reading code in a monospace font - this is the standard in IDEs and terminals. Reading code in a non-monospace font is often harder to parse, and look jarring.

In markdown, you can add a language modifier after the triple backticks (e.g. ```json) to get syntax highlighting. To get syntax highlighting In Google Docs, you can: paste in code from your IDE; or use an add-on Example ```json { "hello": "world" } ``` Why? Syntax highlighting can help make the code more readable, especially when it's in the context of a document full of other kinds of text. It can also help identify problems with examples and code snippets. ~ https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Syntax_highlighting

Don't embed a screenshot of code - paste in the original code into the body of the document as raw text. To learn how to get syntax highlighting in Google Docs, see #4 Why? Screenshots can't be easily updated. The original author has to go back to their IDE and take a new screenshot. Coauthors would have to retype the whole thing out. In Google Docs, you can't comment on specific lines - only the image as a whole. Accessibility - screenshots can't be read out be screen readers, colors can't be changed, the font size can't be increased without blurring etc...

Ordered lists can be a great way of structuring a large section of a document - for example, the implementation of each milestone may get its own section, with a numbered section header. If the "list" starts to span multiple pages, it's harder for the reader to get an overall sense of how many sections there are, and where they are on the page in the context of the list. Provide a "summary list" (like a mini table of contents) at start of the list to give the reader a heads up! Example Here are all the meals I eat in a day: Breakfast Lunch Second lunch Dinner Miidnight snack To give a full breakdown: What I eat for breakfast For breakfast, I eat sweet potatoes, marshmallows, haddock, ice cream, margarine, applesauce, chutney, potatoes, bourbon, squash, heavy cream, watermelons, asiago cheese, amaretto, duck, portabella mushrooms, gelatin, brown rice, breadcrumbs, zinfandel wine, adobo, cantaloupes, garlic powder, herring, red beans, cilantro, ginger, gouda, almond paste, potato chips, won ton skins, turtle, liver, shitakes, cranberries, tofu, beans, curry powder, couscous, mackerel, monkfish, sushi, steak, rice paper, snapper, wine vinegar, Havarti cheese, cream cheese, pico de gallo, spearmint, plums, salmon, celery, alfredo sauce, ginger ale, bagels, pears, dumpling, and cider. I occasionally also enjoy mussels, potato chips, parsnips, eggplants, apples, chocolate, breadcrumbs, cornmeal, truffles, fennel, ricotta cheese, chicory, marshmallows, beets, mascarpone, dried leeks, cactus, vanilla, mozzarella, rice vinegar, horseradish, wine vinegar, custard, corn flour, bean threads, spinach, mayonnaise, turkeys, prawns, chestnuts, plum tomatoes, pinto beans, tuna, oatmeal, milk, sweet potatoes, cider vinegar, almonds, lima beans, catfish, vermouth, pork, spaghetti squash, chili powder, buttermilk, and Parmesan cheese. In particular, I like brown rice, vinegar, bourbon, jack cheese, salt, yogurt, black olives, allspice, swordfish, beans, barbecue sauce, apricots, pea beans, grapefruits, blackberries, capers, kiwi, tea, borscht, Tabasco sauce, focaccia, cloves, basil, raspberries, cream cheese, parsley, granola, cranberries, olive oil, squid, portabella mushrooms, ancho chile peppers, kumquats, hazelnuts, geese, tofu, maraschino cherries, baguette, potatoes, angelica, swiss cheese, tomatoes, grits, peas, zinfandel wine, panko bread crumbs, bay leaves, amaretto, bananas, prosciutto, limes, cremini mushrooms, water, summer squash, soybeans, rosemary, rice, melons, beer, venison, green onions, peanuts, romaine lettuce, cocoa powder, and gouda. What I eat for lunch Lunch is the second most important meal of the day. For lunch, I typically eat peanuts, cod, garlic.......

When referencing technical terms, try and always use its canonical spelling and casing. For example, "GraphQL" should always be written as such - instead of "graphql", "graphQL" or "Graphql" etc. If you're not sure about the spelling of a certain noun, the official homepage of it typically contains the proper spelling for you to look up. Why? A reader might already be familiar with the term - to see it spelled differently may look jarring and distract from your content. Consistent spelling and casing is important so the reader can scan through and recognize the term more easily Examples Node.js (instead of Node or Node.JS) JavaScript and TypeScript (instead of Javascript and Typescript or JS and TS) PostgreSQL (instead of Postgres or Postgresql) MongoDB (instead of Mongo) GitHub (instead of Github) (inspired by https://www.prisma.io/docs/more/style-guide/#capitalize-and-spell-out-proper-nouns)

Why? Reading through a list can be visually tedious and it may be difficult for the reader to remember all of the points being made. Make the first sentence or phrase a summary. This can be emboldened to make it stand out and easier for the reader to scan through. This helps them summarize the points, which should make it easier to remember the points being made. Here are some real world examples: https://github.com/github/gitignore/tree/c851a10cab28082fcfbe5cecce52c4b5edca1d7c#contributing-guidelines https://github.com/yarnpkg/yarn/tree/d8171345b5d8d68cd82fec0899166ee9cda3b03c#features https://www.collaborativefund.com/blog/a-few-rules/

Avoid temporal information. Content that describes something only relevant today will be less relevant to readers tomorrow. Avoid adding information that is likely to go stale over time, because we then have to commit to keeping it up to date over time. For example, we may want to document a new process after a migration, but we don't want to include details of how to migrate, or the historical context about why we migrated. It likely isn't directly relevant to folks trying to understand how to use the current architecture. Such information however is an excellent candidate for a blog post! Blog posts are well suited for migration details, historical context etc since they are timestamped, and intended to be read in the context of the date it was published.