Building a Documentation System in Notion Inspired by AWS and Google

30 April 2025 By  Eugene Evenwel Culture

aws_google_documentation_webeng_%281%29.png

Introduction

Documentation is the backbone of knowledge-sharing in successful engineering organizations. Tech leaders like Amazon Web Services (AWS) and Google attribute much of their success to robust documentation practices – both for internal engineering use and for customer-facing guides. For example, AWS treats its official documentation as the “source of truth” for users, and takes rigorous steps to ensure accuracy. Google, similarly, invests in clear style guidelines and treats documentation as a core part of code health. Yet many developers face “blank page” syndrome or uncertainty about what’s expected when they sit down to write docs. This guide distills proven documentation standards and best practices from AWS and Google into a practical system your team can implement in Notion. It provides repeatable processes, templates, checklists, and style conventions to help developers create and update documentation confidently and consistently. The goal is to foster a documentation culture where writing and maintaining docs is natural, efficient, and even rewarding – with minimal friction for new team members.

Core Principles of Effective Documentation (Lessons from AWS & Google)

  • Clarity & Consistency: Both AWS and Google enforce a consistent writing style to make documentation easy to read and scalable across thousands of pages. Google’s technical writing guidelines emphasize using second person, present tense, and active voice for a direct, conversational tone. AWS’s documentation style guidance is similar: “use active voice, use present tense, write to the user in second person,” and maintain consistent terminology and formatting. This means writing “You configure the server by running…” instead of passive constructions like “The server is configured by running…”. A consistent voice and formatting (headings, code examples, callouts, etc.) across all docs ensures readers can easily navigate and trust your documentation. It also helps multiple authors write as one unified team.
  • Audience-Focused & Purposeful: Great documentation is always written with a specific audience and purpose in mind. As Googler Raphael Moutard notes, “Who is your audience? … Adapt your style” accordingly. Before writing, clarify whether you’re targeting internal developers, end-users, ops/SRE, etc., and what you want them to learn or do. For user-facing guides, Google’s style guide recommends addressing the reader as “you” to keep content user-focused. Avoid internal jargon that outsiders won’t understand, or if you must use a term or acronym, define it on first use. For internal docs, consider the knowledge level of new hires – provide enough context and avoid assuming too much historical knowledge. Every document should have a clear “Why am I writing this?” and “Who is this for?” – this prevents rambling or including irrelevant details.
  • Accuracy & Single Source of Truth: Documentation must be correct and up-to-date to be useful. Stale or wrong information is worse than none at all. Google’s internal best practices put it bluntly: “A small set of fresh and accurate docs is better than a large assembly of ‘documentation’ in various states of disrepair.” Teams are advised to cut out unnecessary, out-of-date, or redundant info and continually refine docs to keep them “alive”. Both Google and AWS avoid duplicating information in multiple places – instead, one canonical source is referenced everywhere (DRY – Don’t Repeat Yourself). Google explicitly calls out that “Duplication is evil”: if a guide for a common technology exists, link to it rather than writing your own; if it’s outdated, contribute updates to the original. In practice, this means using cross-links in Notion or shared pages instead of copying content. When using command references or API details in a how-to guide, link to the reference instead of re-listing all the parameters. This keeps maintenance simple and avoids contradictions. AWS likewise restructured its docs to improve consistency and findability, bringing common info “front and center” and cross-linking related resources like CLI and API references. The takeaway: ensure every fact lives in one place and that your team knows to update the docs whenever the code or behavior changes.
  • Examples and Code Over Prose: Developers often prefer examples – “Don’t make me read – just show me some code,” as AWS learned from feedback. Both AWS and Google include plenty of code samples, configuration snippets, and step-by-step examples in their documentation to complement text. Make liberal use of examples, screenshots, and diagrams (when appropriate) to illustrate usage and edge cases. This not only helps human readers but even improves how well AI tools (which scan your docs) can answer questions about your system. When writing a guide in Notion, you can embed code blocks or images to show, not just tell. For instance, instead of describing a JSON config in words, show a snippet of that config file. Ensure examples are correct and tested – nothing erodes trust faster than a “copy-paste” example that doesn’t work.
  • Continuous Improvement (Docs are Living Assets): Treat documentation as a living part of the product, not a one-time task. AWS continually refactors and optimizes its documentation for readability and structure. Google makes it a habit to update documentation with every code change and to delete or fix “dead” documentation that is no longer accurate. Encourage a mindset that documentation is never “done” – there’s always room to clarify, to remove outdated sections, to add a Q&A for a common support issue, etc. One approach is to allocate a little time in each sprint for doc maintenance or have periodic doc reviews. Google’s guidance suggests involving the whole team in cleanup efforts: scan docs and decide “keep or delete” on anything stale. The result is lean, relevant docs that people trust. Internally at Amazon, writing is part of the culture – “if there’s no document, it doesn’t get done” – and there are training and review practices to help engineers improve writing over time. Adopting a similar philosophy, where writing is valued and improved iteratively, will raise the quality of your documentation corpus continuously.

Documentation Workflow in Practice

To make documentation sustainable, integrate it into your team’s existing development workflow. Here is a repeatable process, inspired by AWS and Google, that your team can follow for creating and updating docs:

  1. Plan & Choose the Doc Type: When a new feature or project is starting (or an existing one changing), decide what documentation is needed. For a major design or feature, an internal design document might be required for team review (Google often uses design docs for this purpose). If you are delivering a user-facing feature, you’ll likely need to update the user guide or API reference. Identify the audience and goal – is this an internal how-to for developers, a runbook for IT, or a tutorial for end users? This determines the template and tone. Also decide the scope: sometimes a few comments in code or an updated README is sufficient (Google advises updating README and code comments alongside code changes), whereas bigger changes need separate documentation. Use a simple decision framework:

    • Small code change or bugfix? – Update code comments or inline docs in the code itself, and ensure any user-visible effect is noted in relevant existing docs (no new doc needed).
    • New feature or component? – Draft a brief design doc internally (for peer review of approach), then add or update a user guide section or release notes for external users.
    • New product or major module? – Create full documentation set: overview, how-to guides, API references, etc., possibly starting from a template set.
    • Operational process or runbook? – Write an internal how-to guide so the team can repeat the process reliably (and update any existing SOP docs).

    This upfront planning ensures you’re not writing docs for the sake of it, but to serve a clear need. It also helps prevent over-documenting or under-documenting.

    Tip: In your Notion workspace, maintain a simple table of planned documentation items (with fields like Doc Name, Type, Owner, Status) whenever new projects kick off, so it’s clear who is responsible for which docs.

  2. Use Templates to Draft Content: Starting from a template eliminates the blank page fear and guarantees that important sections aren’t forgotten. At this stage, pick the appropriate Notion template (or page structure) for the document type. For example, use the “Design Doc Template” for internal proposals, or the “How-To Guide Template” for user instructions (sample templates are provided in the next section). Copy the template into your project’s docs space in Notion and fill out each section with information. Focus on getting the key points down in each section rather than writing perfect prose on the first pass. Remember the style principles while drafting: write in a straightforward manner, addressing the reader directly and actively. If uncertain how to phrase something, it can be helpful to look at an example from AWS or Google’s docs for inspiration – notice how they introduce a topic, or how they list steps clearly. Use headings, lists, and tables to structure information in an easily scannable way (both AWS and Google heavily use formatted lists for procedures, and tables for feature comparisons or parameters). Avoid long walls of text; shorter paragraphs and plenty of whitespace make it more readable (a rule of thumb is ~3-5 sentences per paragraph). Also, add placeholders for any examples or diagrams you plan to include (e.g., “(insert example code snippet of usage here)”) – this reminds you to include them and immediately shows reviewers where illustrative material will go.

  3. Review and Revise: Just as code benefits from code review, documents benefit from peer review. Before considering a doc “done,” have at least one other person read it – ideally a mix of perspectives (another developer for technical accuracy, and someone less familiar with the feature for clarity). Google’s engineers are encouraged to include documentation changes in code reviews; you can mirror this by making documentation updates part of the pull request process (if using a docs-as-code approach) or by explicitly sharing the Notion doc for review when a feature is ready. During review, ask the reviewer to verify:

    • Technical accuracy: Are all statements, command examples, config values, etc. correct and up-to-date with the latest implementation? (Docs should reflect reality 100% – recall AWS’s insistence on accuracy since customers rely on them.)
    • Clarity and completeness: Can a new person follow the guide without confusion? Are all necessary steps or concepts explained? Identify any jargon or assumptions that need clarification (e.g., terms a newcomer might not know).
    • Consistency and style: Ensure the writing follows the style guidelines (voice, tone, terminology). Check that headings, formatting, and cross-references are used properly. For example, are we capitalizing things consistently? Did we address the user as “you” throughout? Small things like the wording of a step (“Click Submit” vs “Press the Submit button”) should align with a unified style.
    • Organization: Check if the document flows logically – e.g., introduction provides context before diving into steps, steps are in order, related info is grouped.

    Incorporate the feedback by editing the Notion doc. This may require a couple of iterations (just like code). Don’t be afraid to rewrite sentences for simplicity – clarity trumps verbosity. As AWS documentation team described when using AI to draft content: the first draft is only a starting point, and they “thoroughly tested and revised the content to meet … standards before publishing.”. We should apply the same rigor: iterate until the doc meets your team’s standards.

  4. Publish & Organize: Once reviewed and refined, make the documentation easily accessible to its audience. In Notion, this could mean moving the page from a private draft space to a public team space or adding it to an index of docs. For internal docs, you might have a “Documentation” homepage in Notion where all important docs are linked or categorized (e.g., by project or by type). Ensure your new document is linked in the relevant places:

    • If it’s a user guide or external-facing doc, you may need to export or copy it to a publicly accessible format (Notion can publish pages to web, or you might migrate the content to your developer portal).
    • If it’s an internal design doc, link it from the project’s main page or the engineering wiki index.
    • Update any related documentation: for instance, if this was a feature addition, update the master user guide table of contents, or add a reference from an overview page saying “for details on X, see [New Feature Doc]”.
    • Communicate the new or updated documentation to the team (and to users, if external). A quick post in Slack or email like “FYI: Documentation for feature X is now available here…” encourages others to use it. At AWS, documentation improvements are communicated and shared widely – they even highlight big doc changes in blog posts. Imitate this by treating significant docs as deliverables worth announcing.

  5. Maintain & Evolve: After publishing, the work isn’t over. Assign ownership of the document (usually the feature owner or team) to ensure it stays current. When code changes, make it a habit to change the documentation in the same commit or task (Google’s rule: “Change your documentation in the same CL as the code change.”). This keeps docs from lagging behind. If using Notion manually, you can still coordinate: e.g., when a PR merges, have a checklist item “update docs” and link to the Notion page for the feature. Regularly schedule reviews for long-lived docs – for example, an agenda item in quarterly retrospectives could be to spot-check some docs for accuracy. If something is found to be outdated or redundant, fix it or remove it. Google advises to ruthlessly delete dead documentation rather than let it mislead – better to have fewer, accurate docs than many stale pages. In Notion, you might maintain an archive for obsolete docs (don’t clutter active spaces). Also gather feedback: if teammates or users ask a lot of questions that the doc should have answered, improve the doc. Treat documentation as a continuous improvement project, similar to how AWS uses user feedback (thumbs-up/down metrics, support tickets, etc.) to iteratively enhance their docs.

By following this workflow, documentation becomes a natural part of development: from planning (decide doc needs) to coding (updating docs with code) to code review (catch doc issues) to release (publish docs) and maintenance. Embedding this in your process ensures docs don’t fall through the cracks or become an afterthought.

Templates and Structure Guidelines

Structured templates take the guesswork out of documentation and help ensure all necessary information is captured. Below are sample templates for two common documentation types – an internal design document and a user guide/how-to article – distilled from patterns used at Google and AWS. These can be created as Notion templates for your team to clone whenever needed. Feel free to adjust them to your context. Each template includes section headings with brief explanations of what to include:

Template: Software Design Document (Internal)

(Use this when proposing a new system or feature, or documenting an architecture change. Inspired by Google’s internal design docs and Amazon’s narrative approach to proposals.)

  • Title and Metadata: Project/Feature Name – Design Document.
    • Author(s): Alice Doe, Bob Smith
    • Last Updated: 2025-04-30
    • Status: Draft / In Review / Final
  • Overview / Abstract: A one-paragraph summary of the design or proposal. Example: “This document outlines the design for adding multi-factor authentication (MFA) to the user login process, including the proposed architecture, trade-offs, and rollout plan. Our goal is to enhance security for high-value accounts without significantly degrading user experience.” This overview lets a reader know what the doc is about and why it exists.
  • Background & Context: Briefly describe the context and why this work is needed. What problem are we trying to solve? What assumptions or prior decisions frame this proposal? If relevant, link to previous docs (prior designs, requirements, Amazon-style PR/FAQ if one exists, etc.). Keep it concise and focused on information the audience (your team and stakeholders) needs to understand the design choices later. Avoid deep lore or unrelated history.
  • Goals and Non-Goals: List the objectives of this design and also clarify what is out of scope. Google design docs often explicitly state non-goals to prevent scope creep. Example: “Goal: Enable MFA for high-risk user accounts to reduce account takeover risk. Non-Goal: This design does not cover authorization/permissions – only authentication.” This sets clear expectations for what the design will achieve.
  • Design Details: This is the core of the document. Structure it into subsections as needed:
    • Proposed Solution: Describe the solution in detail. This might include a high-level approach followed by specific components or steps. Diagrams or flowcharts can be extremely helpful here (Notion supports embedding images or using draw.io and pasting an image). For complex systems, break this into subheadings (e.g., Architecture, Data Model, Component A, Component B). Describe how the pieces fit together. Focus on how it works and why it’s designed that way – provide rationale for key decisions (for instance, “We chose AWS Cognito for user management because it integrates with X.”). Keep the language straightforward and factual – avoid marketing fluff or unsubstantiated claims (Amazon’s writing guidelines warn against “peacock words” – i.e., praise without specifics).
    • Alternatives Considered: Briefly describe other options you evaluated and why you didn’t choose them. This shows you’ve thought through the problem and helps future readers understand the trade-offs. It can be a simple bullet list of pros/cons for each alternative. (If there were no serious alternatives, you can state that, or use this section to discuss major trade-offs in the chosen approach.)
    • Challenges & Risks: Note any known risks, unknowns, or potential issues in the design. For example, “This approach requires integrating a new third-party service, which could introduce latency or downtime risk.” Being upfront about risks reflects Amazon’s data-driven honesty in docs (back claims with data and be clear about pitfalls). If you have mitigation plans, note them here.
    • Assumptions: (Optional) List any assumptions that must hold true for the design to succeed (e.g., “We assume at least 50% of users will opt into MFA, which is necessary for the desired security improvement. This is based on earlier survey data.”).
  • Implementation Plan: Outline at a high level how you plan to implement this design. This can include phases or milestones, who will do the work, and an estimated timeline. This section turns the design into actionable steps, which is helpful for the team and project managers. If this doc is just for documentation (and implementation is already done), you might retitle this section as “Implementation Details” and instead summarize how it was actually built.
  • Rollout & Migration Plan: If the change impacts an existing system or users, describe how it will be rolled out. For example, will it be behind a feature flag, gradually enabled, or a big bang release? How will you migrate data or user settings if needed? AWS design docs often consider backward compatibility and customer impact, so include notes on monitoring, fallback plans, or communications needed.
  • Open Questions: (Optional) List any open issues or points requiring further discussion/decision. It’s okay if a design doc doesn’t have every detail finalized – calling these out invites readers to weigh in. For instance, “Open Question: Should we make MFA mandatory for all users eventually? (Not decided yet).”
  • Appendices / References: Provide links to any relevant materials: requirements docs, user research, relevant AWS or Google cloud architecture reference, etc. Also, if you have detailed data (like performance numbers, cost analysis) that would clutter the main text, include them in an appendix section here or as an attached spreadsheet.

This design doc template ensures a thorough discussion of a proposed change. It follows a logical narrative (context → proposal → deeper details → plan → questions) much like Amazon’s narrative docs, but also structured enough that someone can skim to find specific info (like just the risks, or just the alternative considered). By filling in this template, a developer addresses the important aspects up front, and reviewers know where to look for specific information. Once the feature is implemented, remember Google’s advice: the design doc becomes an archive of the decision google.github.io – you might add a note like “Status: Implemented in version 1.2, archived for reference” at the top, and ensure the live user-facing documentation is updated accordingly.

Template: User Guide / How-To Article (External or Internal)

(Use this for any instructional documentation: how to accomplish a task with your software, a configuration guide, a runbook, etc. This is similar to the structure of AWS “Getting Started” or “How do I…?” topics, and Google’s task-oriented help articles.)

  • Title: How to [Do Something] with [Product/Tool].

    Example: “How to Set Up Two-Factor Authentication for Your Account”.

    Good titles are short and clearly state the task or subject. (Avoid vague or clever titles – users typically search by task, e.g., “setup 2FA AWS accounts”.) For internal guides, you might include the system name too, like “Deploying Service X to Staging – Step by Step”.

  • Introduction/Purpose: 1-3 sentences stating what this guide covers and why it’s useful. Identify the audience if needed. Example: “This guide explains how to enable two-factor authentication (2FA) on the internal admin dashboard for added security. It is intended for all developers and support engineers who have admin access.” Keep it succinct. AWS often starts user topics with a brief sentence or two of what and why, so the reader knows they’re in the right place.

  • Prerequisites: A bulleted list of any requirements or assumptions before one can perform the task. This might include access rights, prior setup, or specific tools. Example: “Prerequisites: 1) An active admin account on the dashboard, 2) A mobile device with Google Authenticator installed.” If none, you can omit this section, but most how-to guides have at least some context (for instance, a Google Cloud how-to will list that you need a Google Cloud project and specific API enabled). Ensure these are explicit so a user doesn’t get halfway and realize they’re missing something.

  • Steps/Procedure: This is the main part: a numbered list of steps to accomplish the task. Write each step as a directive in clear, active voice. For example:

    1. Log in to the admin dashboard with your username and password.
    2. Navigate to Settings > Security.
    3. Click Enable Two-Factor Authentication.
    4. Scan the QR code with your authenticator app and enter the generated code to verify.
    5. Click Confirm to finalize enabling 2FA on your account.

    Make sure each step is precise and includes any sub-instructions or expected outcomes. If a step might confuse a newbie, add a brief clarification. For instance, if scanning a QR code isn’t obvious, mention which app to use. Use bold to highlight UI elements or buttons (as shown above) – this is a common convention in tech docs to distinguish what the user should click/see. If the process branches (conditional steps), you can use sub-bullets or notes like “If you have X, do Y; otherwise, skip to next step.” Keep each step digestible; if a step is too long, consider breaking it into sub-steps or separate steps.

  • Example / Screenshot (if applicable): It often helps to show a screenshot of a completed form or a code snippet as an example. For instance, if step 4 above had the user enter a code, you might show an image of what the screen looks like after enabling 2FA. Or if this were a CLI guide, show the command and expected output. Make sure to add alt text or a caption in Notion for images (AWS made alt-text improvements a priority for accessibility). Example for a CLI guide:

    $ aws acme enable-2fa --user alice
Two-factor authentication enabled for user alice.

    Including copy-paste friendly command examples (with any placeholders clearly indicated with angle brackets or similar) is a Google documentation best practice. In Notion, you can use a code block for this. Always test your example commands or code to ensure they actually work as shown!

  • Outcome/Verification: After the steps, tell the reader how to confirm they did it right. Example: “You should see a message ‘Two-factor authentication is enabled.’ From now on, your account will require a code at login.” This reassures the user and closes the loop. It’s similar to how AWS docs often say “When successful, you see output similar to: …”.

  • Troubleshooting / FAQ (optional): If there are common issues or questions related to this task, list them here with solutions. For example: “Q: I didn’t get a code, what do I do? A: Ensure your phone’s time is synced…”. This section can be added over time as you get feedback on the guide. Google’s user help often links out to a separate troubleshooting section; you can either link to a central FAQ or include key Q&A directly if it’s brief.

  • Next Steps / Related Documentation: Finally, point the reader to what they might do next. Example:“Next Steps: Now that 2FA is enabled, you may want to read the Security Best Practices guide. If you need to disable 2FA, see Removing 2FA in the admin guide.” This mirrors how AWS and Google docs cross-link extensively to keep users moving through the documentation logically. It prevents dead-ends and encourages users to discover relevant info.

This how-to template ensures a task-oriented document that is easy to follow. It separates the necessary setup (Prerequisites) from the actions to take (Steps), and provides support info as needed (examples, troubleshooting). By following this structure, developers know exactly how to format their guides: a short intro, then a list of actions. This directly addresses the resistance of “I don’t know how to start writing this” – the template itself tells you what to write next (e.g., “Okay, now I list the prerequisites, now I list the steps…”). Notion can store this template page in a central location (perhaps a “Templates” database or page) so anyone can duplicate it and just fill in the blanks.

Tip: You can create more templates for other doc types as needed – for example, an API Reference template(with sections for Endpoint, Method, Parameters, Response, Examples), or a Runbook template (with sections: Purpose, Trigger, Steps, Rollback, etc.). The key is to standardize whatever types of docs your team produces frequently. AWS has hundreds of service API references that all look alike in structure; you can achieve a similar consistency by following the same outline every time for a given doc type. The result is that readers (and writers) know what to expect. A new team member glancing at one of your how-to guides will immediately recognize the pattern: intro, prerequisites, steps… – this predictability lowers the effort needed to use docs effectively.

Style and Formatting Standards

To further ensure consistency and quality, establish some baseline style rules and a content checklist for all documentation. Many of these align with the published style guides of Google and Microsoft (which AWS and others also follow). You can keep a page in Notion called “Documentation Style Guide” that lists these rules for reference. Here’s a condensed version of the most important style and formatting conventions to adopt:

  • Use Active Voice and Present Tense: Write sentences so that the subject performs the action. “The system sends an email” instead of “An email is sent by the system.” Active voice makes sentences clearer and more direct. Use present tense for general truths or current capabilities (e.g., “This function handles user login” – assuming it does so in the current version). Past tense can be used for historical descriptions or when referring to a past version (“In v1.0, the module was named X”). This guideline is straight from Google’s playbook for developer docs, promoting clarity.
  • Address the Reader as "You": In user guides especially, speak to the user directly. For example, “You can configure the settings by…” or in steps, imperative mood like “Install the package by running…”. Avoid third person like “The user can configure…” as it creates distance. Second person (you) is friendlier and assumed in instructional text. For internal docs (design docs, etc.), second person is less common; you might use first person plural (“We”) when describing team decisions, or simply an impersonal tone. But for anything tutorial-like, stick to “you” for consistency with industry norms.
  • Be Concise and Specific: Developers value their time. Write concisely – omit unnecessary words and avoid repetition. Amazon’s writers are trained to “be concise” and avoid fluff. For instance, instead of “was able to successfully unblock the situation,” just say “unblocked the situation”. At the same time, include specific details and data where precision is needed. Avoid vague terms like “many”, “often”, “might” without context. As one Amazon style tip says, “avoid weasel words” that create an illusion of meaning. If you have numbers or facts, use them: e.g., instead of “many users”, say “301 users (12% of our user base)”. Being specific instills confidence and helps the reader understand scope. It’s also part of being data-driven in writing.
  • Avoid Jargon and Explain Acronyms: Use simple, widely-understood terms whenever possible. If you must use domain-specific jargon or abbreviations, explain them on first use. Google’s style guide and Amazon’s writing training both stress this. For example, write “Set up a Virtual Private Cloud (VPC)” rather than “set up a VPC” with no context. Once defined, you can use the acronym going forward in the document. If a term is only relevant to a small audience, consider if it’s needed at all. Prefer clear, descriptive terms (for instance, instead of a code-named internal project, use a functional description). This makes documentation accessible to newcomers and people outside your immediate team.
  • Consistent Terminology and Naming: Establish standard terms for your product features and stick to them across all documentation. If your UI says “Organization” (not “Company” or “Tenant”), then documentation should use “Organization” exactly as labeled. AWS and Google docs maintain strict consistency in naming; they even maintain word lists of preferred terms. You might create a mini glossary in Notion for your own common terms. Likewise, when talking about external technologies, use the official names (e.g., “AWS Lambda” not “Lambda Function” if that’s not the official term). Consistency avoids confusing the reader. This extends to how you format certain terms: for example, decide on American vs British spelling (Google and AWS use American English), whether to use the Oxford comma (Google does use the serial comma), etc., and apply it uniformly.
  • Structure Headings and Lists Properly: Use the correct heading levels in Notion (or markdown) to create a logical hierarchy. For instance, in a long user guide, an H2 for each major task, H3 for sub-steps or sub-topics. Use sentence-case capitalization for headings (capitalize only the first word and proper nouns) unless your style prefers Title Case. Consistent heading style makes the docs look professional. When listing steps or items, use numbered lists for sequences and bullets for unordered points. Always lead into a list with a sentence or clause (avoid starting a section with a naked list without context). Each list item should be parallel in structure (all steps as commands, or all items as fragments that continue the intro sentence). These formatting details might seem minor, but they greatly improve readability when followed everywhere.
  • Highlight Important Notes: Both AWS and Google documentation use callouts for important information (notes, tips, warnings). In Notion, you can use the “Callout” block or simply bold key phrases like “Note:” or “Important:” at the start of a paragraph. Use these sparingly for things the user must know (e.g., a prerequisite that if missed could cause failure, or a caution about irreversible actions). Do not bury critical warnings in the text. For example: “Warning: Enabling this feature will reset all current sessions.” stands out and ensures the reader sees it. Consistency in how you format these callouts (same wording and style) across docs helps users spot them. Also, maintain a positive, helpful tone even in warnings – the goal is to inform, not scare or blame the user.
  • Use Tables and Diagrams When Appropriate: If you need to convey structured information (comparisons, options, configurations), consider a table format. AWS’s decision guides, for instance, lay out service differences in tabular form for clarity. In Notion, you can create a simple table or even paste an image of a more complex diagram. Visual aids can often convey in one diagram what might take a page of text – just ensure to accompany them with explanatory text. Every image or diagram should have a caption or alt text describing its gist (for accessibility and for users who skim). Keep diagrams up-to-date as the system evolves (this is often forgotten – outdated diagrams are a form of stale doc).
  • Proofread for Grammar and Typos: This goes without saying, but basic grammar, spelling, and punctuation must be correct. It reinforces professionalism and credibility. Google’s style guide provides detailed grammar rules and even preferred spellings of tech terms (e.g., use “email” not “e-mail”). You don’t need to memorize all of these, but do a pass to catch obvious errors. Tools like Grammarly or even Notion’s built-in spellcheck can help. Also check that all links in the doc work, and that references to UI labels or API parameters match the actual current names (something easy to miss if the UI changed).

By adhering to these style guidelines, your documentation will read with the polish of AWS’s and Google’s docs – clear, consistent, and user-friendly. Over time, these conventions become second nature to the team. You might even create a one-page checklist version of the style rules that writers can quickly glance at before finalizing a doc (e.g., a bullet list: “✅ Active voice, ✅ Second person,” etc.). In fact, here is a quick Documentation Quality Checklist summarizing many points above that writers and reviewers can use.

Documentation Quality Checklist (for Review & Approval)

Before marking a document as complete, run through this checklist to ensure it meets our standards. This applies to any type of documentation (design docs, user guides, etc.) and can be used by the author for self-review and by peers during review. In Notion, you can even make these as actual checkboxes in a template for easy use:

  • [ ] Purpose & Audience Clear: The document’s intro clearly states what it’s for and who should read it. The content stays on-topic and relevant for that audience.
  • [ ] Template Sections Completed: All sections of the chosen template are filled in, or marked "N/A" if not applicable. (No section was left empty without explanation.)
  • [ ] Accuracy: Technical facts, commands, code, and outputs have been verified against the current version of the system. No known incorrect information is included.
  • [ ] Up-to-Date Links/References: All hyperlinks or cross-references point to the right and current resources. (No links to deprecated APIs or old wiki pages unless needed with context.)
  • [ ] Clarity & Simplicity: The language is simple and free of unnecessary jargon. Acronyms are spelled out on first use. Complex concepts (if any) are explained or diagrammed. A new hire or user with the expected background should understand the doc without needing extra explanation.
  • [ ] Step-by-Step Validity: (For procedural docs) Each step has been walked through by the author or tester. The procedure actually works as written in the order presented. There are no missing steps or unclear instructions.
  • [ ] Consistent Terminology: The document uses consistent names for products, features, and variables (and they match the UI or code exactly). No mixing of synonyms that might confuse (e.g., don’t call the same thing "login" in one place and "sign-in" in another).
  • [ ] Proper Formatting: Headings, lists, and formatting follow our style. Important notes use callouts. Items meant to be literal (like file names, commands, code) are in code style or quotes. The document is easy to scan for key parts (good use of paragraphs, subheadings, or bold where appropriate).
  • [ ] Tone & Voice: The tone is professional yet approachable – it doesn’t talk down to the reader or overflow with slang. It uses active voice and addresses the user as "you" where appropriate. It avoids filler phrases (e.g., "In order to", "Please be aware that" can often be shortened or removed).
  • [ ] No Spelling/Grammar Errors: The prose has been spell-checked. Sentence structure is sound. (If the document is customer-facing, this is especially critical – it should reflect well on the product’s quality.)
  • [ ] Images/Examples Quality: Any screenshots are current and sanitized of sensitive data. Any code examples have been tested to produce the shown output. All example placeholders (<like this>) are clearly distinguishable and explained.
  • [ ] Metadata & Ownership: The document has an author or owner listed (if not obvious) and a last updated date. It’s filed in the correct category or folder in Notion. If appropriate, it’s linked in the master index or relevant section so others can find it.
  • [ ] Peer Reviewed: At least one other team member has reviewed this document for content and quality (and this checklist has been considered). All feedback has been addressed or resolved.

When all the boxes are checked, the documentation is in great shape to publish or share. This checklist echoes what a tech writer at AWS or Google would verify during their editorial review process. In fact, AWS mentions that even AI-generated docs go through a human edit to ensure they meet their documentation standards – think of these checklist items as those standards. By institutionalizing this review checklist, you reduce variability and catch issues early.

Onboarding New Team Members with the Documentation System

A documentation system only works if people use it. To ensure new (and existing) team members adopt these practices with minimal friction, take the following steps in your Notion workspace and team process:

  • Centralize Documentation Resources: Create a Notion “Docs Home” page that serves as a one-stop portal. This page should explain the documentation process briefly and link out to:
    • The Templates (design doc, user guide, etc.) – so newcomers can easily grab the right starting point. Notion allows creating a template gallery or you can list them as sub-pages for easy duplication.
    • The Style Guide and Checklist (from above) – so they know guidelines and quality expectations.
    • Examples of Great Documentation – link to a couple of well-written docs (maybe one internal, one external) that you consider models. If your company already has some good docs, point them out as reference. If not, you might even link to a publicly available example (for instance, an AWS tutorial or Google Cloud guide that is similar to what you want), to illustrate the end goal in context.
    • How-To for Using Notion for Docs – a short guide on any conventions you use in Notion (for example, how to tag docs, how to request a review by mentioning a person, how to use the “last updated” property, etc.). Notion is generally intuitive, but if you have set up a docs workspace with databases or specific workflows (like an approval status), document that here.
  • Introduce the System in Onboarding: As part of onboarding a new engineer, have a quick session or document on “How we do documentation.” Emphasize that writing is a normal part of the dev job (this is how Google and Amazon set the tone – writing is valued, not an extra chore). Provide the new hire with the Notion Docs Home link. Make sure they know that whenever they start a task or project, they should consider documentation needs as explained above. Often the fear or reluctance comes from not knowing where to start or what’s expected – by clearly laying this out, you remove that uncertainty. In essence, “all developers can write great documentation once they have the right tools to guide them.” thegooddocsproject.dev
  • Encourage Early and Small Contributions: To get new folks comfortable, encourage them to contribute small documentation updates early on. For example, during their first bug fix, ask them to update any relevant doc (even if it’s just a sentence change). Google’s practice of updating docs with code commits works best when everyone does it routinely. Positive reinforcement helps – if a newcomer updates the README or user guide, acknowledge it in code review (“Thanks for keeping the docs in sync!”). This builds habit and shows that the team truly values documentation.
  • Mentorship and Examples: Pair new team members with a buddy or mentor who exemplifies good documentation practices. Perhaps have the mentor share a past design doc they wrote, or walk through how they’d approach writing one. Seeing how an experienced engineer tackles documentation can demystify the process. It’s similar to code mentorship – you learn by example. Both AWS and Google have internal training for documentation/writing; you can achieve a lighter-weight version of this with peer mentorship and sharing of best practices in team meetings.
  • Minimize Bureaucracy: Make the documentation workflow as lightweight as possible in tooling. Notion is a good choice because it’s user-friendly and doesn’t require learning a new markup or Git flow for docs (which can be a barrier for some). Use Notion features to your advantage: comments for review feedback, @mention people for input, version history to track changes, etc. Avoid over-engineering the process – the above templates and checklists are guidance, not red tape. Developers should feel that the system helps them (by providing structure and catching errors) rather than restricts them. Keep the tone of guidelines encouraging. For example, if someone makes a good doc improvement, celebrate it and perhaps add it to the example list.
  • Iterate on the System: Finally, treat this documentation system itself as living documentation. Gather feedback from the team on what works or doesn’t. Maybe the template needs tweaking, or the checklist is too long and people skip it – adjust based on input. Over time, you’ll tailor the system to your team’s style. Both AWS and Google continuously evolve their doc processes (Google even solicits feedback on their public style guide to improve it). Do likewise: if developers remain resistant, find out why – maybe they need more training, or maybe the review process can be streamlined. Keep improving the docs about docs.

By embedding these practices into your team culture, documentation will cease to be a painful afterthought. Instead, it becomes a natural part of engineering work, with clear expectations and support. New hires coming from elsewhere might even remark how refreshing it is to have such a well-oiled documentation process! In the long run, adopting AWS and Google’s documentation best practices not only produces better docs for your team and users, but also improves software quality (through clearer thinking) and onboarding speed. Developers can spend more time coding and less time struggling to find or write down information. And perhaps most importantly, good documentation scales alongside your software – enabling your company to grow and innovate faster, backed by a strong shared knowledge base. By following this guide and leveraging Notion as your platform, you can cultivate a documentation culture that rivals the best in the industry.

Sources: The above system is informed by publicly shared insights from AWS’s documentation team and Google’s technical writing guidelines, including AWS blog posts on documentation improvements, Google’s developer documentation style guide, and lessons from Google’s engineering documentation best practices, as well as general technical writing principles. These references illustrate the value of consistent style, integrated workflow, and continuous improvement in producing world-class documentation.

References

Frequently Asked Questions (FAQs)

1. What are the core elements of rigorous documentation standards?

  • Effective documentation standards combine clear templates, a consistent style guide (active voice, second person, British English spellings), version control, peer-review workflows, and a single source of truth. By modelling AWS and Google, you ensure each doc has a defined audience, purpose, structured headings, examples, and regular maintenance.

2. How can we implement AWS and Google’s documentation best practices in Notion?

  • Start by creating Notion templates for each doc type (design docs, how-to guides, API references). Embed checklists for accuracy, style, and peer review, and leverage Notion’s comments and version history to mirror AWS’s editorial process and Google’s “docs-as-code” ethos. This makes it easy for developers to clone, fill in, and publish high-quality docs.

3. What workflow reduces developer resistance to writing documentation?

  • Integrate documentation into every feature backlog: require a draft design doc before development, update user guides alongside code changes, and include documentation updates in pull-request reviews. Offering structured templates and a clear “Docs Home” portal in Notion removes the “blank page” fear and makes writing docs a natural part of the development cycle.

4. Which template structure should be used for internal technical design documents?

  • Use a standard format:
    • Title & Metadata (author, date, status)
    • Overview (purpose and scope)
    • Background & Context
    • Goals & Non-Goals
    • Design Details (architecture, alternatives, risks)
    • Implementation & Rollout Plan
    • Open Questions & References: This mirrors Google’s design-doc approach and Amazon’s narrative style, ensuring clarity and thoroughness.

5. How do we onboard new team members into our documentation culture?

  • Provide a dedicated Notion “Docs Home” page with quick-start tutorials, template galleries, the style guide, and exemplar AWS/Google-inspired docs. Pair new hires with a documentation mentor, encourage early small contributions (e.g., README updates), and celebrate their efforts to reinforce that high-quality documentation is a core part of your engineering culture.