├── README.md └── page-structure.png /README.md: -------------------------------------------------------------------------------- 1 | # How to Make a Docs Site: Shortcuts for Busy Devs 2 | 3 | **Table of Contents:** 4 | - [Introduction](#Introduction) 5 | * [Who This Is For](#Who-This-Is-For) 6 | * [What This Is](#What-This-Is) 7 | * [Who I am](#Who-I-Am) 8 | - [Easy to Maintain](#Easy-to-Maintain) 9 | * [Docs as Code](#Docs-as-Code) 10 | * [Docs Tools](#Docs-Tools) 11 | * [Just Enough Content](#Just-Enough-Content) 12 | - [Easy to Find](#Easy-to-Find) 13 | * [Information Architecture](#Information-Architecture) 14 | * [Types of Documentation](#Types-of-Documentation) 15 | * [Page Structure](#Page-Structure) 16 | * [SEO](#SEO) 17 | - [Easy to Read](#Easy-to-Read) 18 | * [Paragraphs](#Paragraphs) 19 | * [Sentences](#Sentences) 20 | * [Vertical Lists](#Vertical-Lists) 21 | * [Your Reader](#Your-Reader) 22 | - [Conclusion](#Conclusion) 23 | 24 | ## Introduction 25 | 26 | ### Who This Is For 27 | 28 | This article is for **devs** who: 29 | - Are new to making docs 30 | - Want to spend as little time on research as possible 31 | 32 | If you want **maximum results** for **minimum effort**, then you've come to the right place. I put in the time so you don't have to. 33 | 34 | ### What This Is 35 | 36 | This is a **short**, **practical**, and **opinionated** guide. 37 | 38 | You'll get the basic info you need to make a docs site that is: 39 | - Easy to set up 40 | - Easy to maintain 41 | - Easy to use 42 | 43 | You'll learn just enough about: 44 | - Tools 45 | - Information architecture 46 | - SEO 47 | - Technical writing 48 | - Best practices 49 | 50 | By the end of this article, you'll be ready to make your first docs site. 51 | 52 | ### Who I Am 53 | 54 | Hi 👋 I'm Joanna Jablonski. I've been working in **developer education** since 2018. As CircleCI's first Information Architect, I planned the replatforming and restructuring of the docs site. Right now, I'm a Staff Education Engineer at CircleCI. 55 | 56 | Feel free to reach out: 57 | - [jojab.dev](https://www.jojab.dev) 58 | - [GitHub](https://github.com/jablonskidev) 59 | - [Twitter](https://twitter.com/Jo_Jablonski) 60 | - [LinkedIn](https://www.linkedin.com/in/joanna-jablonski-14b9a7140/) 61 | 62 | ## Easy to Maintain 63 | 64 | You can save yourself time and effort if you: 65 | - Treat your docs like code 66 | - Use tools that will make writing and publishing easier 67 | - Limit the scope of your content 68 | 69 | ### Docs as Code 70 | 71 | [Docs as Code](https://www.writethedocs.org/guide/docs-as-code/) is an approach to making docs that lets you use the tools and practices you're already using for code, such as issue trackers, version control, and automation. 72 | 73 | You can: 74 | - Write your docs content in a [markup language](https://en.wikipedia.org/wiki/Markup_language). 75 | - Store those files in a [VCS](https://en.wikipedia.org/wiki/Version_control) to stay on top of changes and request reviews. 76 | - Use a [static site generator](https://idratherbewriting.com/learnapidoc/pubapis_static_site_generators.html) to turn those markup files into HTML, CSS, and JavaScript. 77 | - Use a [CI/CD](https://en.wikipedia.org/wiki/CI/CD) tool to build, test, and deploy. 78 | 79 | ### Docs Tools 80 | 81 | **Which markup language should you use?** 82 | 83 | **Short answer:** [Markdown](https://www.markdownguide.org/) 84 | 85 | **Long answer:** Although markdown isn't as powerful as other options, it is simple and widely used. If you want to invest in learning a more powerful markup language, you can consider [AsciiDoc](https://asciidoc.org/) or [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). Keep in mind that not all languages can be used with all static site generators. 86 | 87 | **Which static site generator should you use?** 88 | 89 | **Short answer:** [Docusaurus](https://docusaurus.io/) 90 | 91 | **Long answer:** Docusaurus is an open-source project maintained by Facebook. It's widely used and has features that are useful for docs sites, such as document versioning and Algolia search. You can use React to customize and embed components in your markdown with [MDX](https://mdxjs.com/). 92 | 93 | Here are some other static site generators: 94 | - [Jekyll](https://jekyllrb.com/) was popular but is now on the way out. 95 | - [Hugo](https://gohugo.io/) builds sites quickly and is becoming more popular. 96 | - [Sphinx](https://www.sphinx-doc.org/en/master/index.html) was built specifically for documentation and integrates with [Read the Docs](https://readthedocs.org/). 97 | 98 | When choosing a static site generator, ask yourself: 99 | - Does it have docs features, such as content reuse? 100 | - Is it based on a programming language that you already use? 101 | - Is it actively maintained by a good community? 102 | - Does it have themes you like? 103 | 104 | ### Just Enough Content 105 | 106 | The less documentation you have, the easier it'll be to keep it up to date: 107 | - **Use just enough code examples:** Give code examples for the most common use cases. Avoid having so many code blocks that some will not be maintained. 108 | - **Make content modular:** Instead of repeating the same information in multiple places, consider linking to one place that is the one source of truth for that topic. 109 | 110 | ## Easy to Find 111 | 112 | You can save your users time and effort if you: 113 | - Structure your docs with their needs in mind 114 | - Help your docs rank higher on Google 115 | 116 | ### Information Architecture 117 | 118 | In order to plan the structure of your docs, you need to know: 119 | - Who will be using your docs 120 | - What your users are trying to do 121 | 122 | For your docs structure to be effective, you need to make sure that it makes sense to the people using the product rather than the people building the product: 123 | - **Structure your docs by task:** Your users are coming to your docs to accomplish tasks. Find out what those tasks are and make sure that there are clear and efficient [click paths](https://en.wikipedia.org/wiki/Click_path) to help your users achieve their goals quickly. For example, if your docs site is for a CI/CD product, your docs homepage could point to sections for building, testing, and deploying. 124 | - **Use the terminology that your users do:** Find out what words they use to describe what they're trying to do. If there's terminology that's specific to your product, new users may not know it yet. If your users aren't experts, they may not think to use more specialized terminology. If they're coming from another product, they may still be using its terminology. When you decide what terminology to use, be consistent. 125 | 126 | Consider doing a [card sort](https://www.toptal.com/designers/ia/card-sorting) with your users to see how they group tasks, terms, and concepts. A card sort can be well worth the time since it'll help you put information where your users expect it to be. 127 | 128 | ### Types of Documentation 129 | 130 | There are four types of documentation that help your users achieve different goals in different contexts: 131 | 132 | | | **Use when studying** | **Use when working** | 133 | |--------------------------------|-------------------------------------|-----------------------------------| 134 | | **Need practical steps** | Tutorials: learning skills | How-to guides: solving problems | 135 | | **Need theoretical knowledge** | Discussions: understanding concepts | Reference: looking up details | 136 | 137 | If you plan your docs using these four types, then the purpose of each page will be clearer. That will make each resource easier to find and easier to maintain. To learn more, check out [Daniele Procida's talk](https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/). 138 | 139 | ### Page Structure 140 | 141 | When your readers look at one of your pages, they need to quickly determine: 142 | - Whether this page has what they need 143 | - Where they need to go next 144 | 145 | Help your users by including: 146 | 1. An introduction that summarizes the topic of the page and the intended audience 147 | 2. A table of contents that shows at least the h2 and h3 headings on the page 148 | 3. A sidebar to show where the page fits in the docs 149 | 4. [Breadcrumbs](https://ui-patterns.com/patterns/Breadcrumbs) at the top of the page to show where the page fits in the docs 150 | 151 | Here's an example of a page with those elements: 152 | ![Page structure](page-structure.png) 153 | 154 | ### SEO 155 | 156 | When your users have a problem, they will go to Google. It's in your best interest that your docs pages rank as high as possible. 157 | 158 | SEO is constantly changing, but there are basic best practices: 159 | 160 | - **Have high-quality, original content:** 161 | - Content that isn't duplicated on another page will rank higher. 162 | - Content that is well-written will rank higher. 163 | - **Add links to your docs pages:** 164 | - Pages that are linked to will rank higher. 165 | - Pages should also link to pages outside your site. 166 | - **Help readers spend a long time on your pages:** 167 | - Avoid publishing pages with very little content. 168 | - Consider embedding videos to increase read time. 169 | - **Use your keyphrases:** 170 | - In the URL 171 | - In the H1 172 | - In at least one H2 173 | - In the first paragraph 174 | - Throughout the page, while avoiding [keyword stuffing](https://developers.google.com/search/docs/advanced/guidelines/irrelevant-keywords) 175 | 176 | Check out Google's [Search Engine Optimization (SEO) Starter Guide](https://developers.google.com/search/docs/beginner/seo-starter-guide). If you want to invest in an SEO tool, consider [ahrefs](https://ahrefs.com/). 177 | 178 | ## Easy to Read 179 | 180 | You can save your readers time and effort if you: 181 | - Make your docs easy to skim 182 | - Focus on your readers 183 | 184 | ### Paragraphs 185 | 186 | Make your paragraphs easy to skim: 187 | - **Use topic sentences:** In the first sentence, summarize the point of the paragraph. When readers skim through the page to find what they need, they'll be able to glance at the start of each paragraph to see if they're interested. Focus on one topic per paragraph. 188 | - **Keep paragraphs short:** Between three and five sentences per paragraph is a good goal. 189 | 190 | ### Sentences 191 | 192 | Make sentences easy to skim: 193 | - **Keep sentences short:** 194 | * Cover one idea per sentence. 195 | * Turn long sentences into [vertical lists](#Vertical-Lists). 196 | - **Write clearly:** 197 | * Use the [active voice](https://developers.google.com/tech-writing/one/active-voice). 198 | * Use [strong verbs](https://developers.google.com/tech-writing/one/clear-sentences#choose_strong_verbs). 199 | 200 | ### Vertical Lists 201 | 202 | Make your vertical lists easy to skim: 203 | - **Use parallel structure:** All of the items in your list need to look like they belong together, so structure all of them in the same way. If one list item describes an action, then all of the list items should. 204 | - **Make your point early:** Start lists of steps with the [imperative](https://www.grammarly.com/blog/imperative-verbs/) form of a verb, such as "Open" or "Delete" rather than "Opening" or "Deleting." 205 | 206 | ### Your Reader 207 | 208 | Focus on your reader: 209 | - **Build sentences around the word "you":** Using "you" will help you avoid the [passive voice](https://developers.google.com/tech-writing/one/active-voice) and focus on what will help your reader. 210 | - **Sound clear rather than smart:** Docs need to remove obstacles for users so they can see how great your product is by actually using it themselves. The more time you save your users with simple docs, the faster they'll see how sophisticated your product is. 211 | 212 | ## Conclusion 213 | 214 | You're ready to make an effective docs site with minimal effort! Your new docs site will be easy to set up, maintain, and use now that you know just enough about: 215 | - Tools 216 | - Information architecture 217 | - SEO 218 | - Technical writing 219 | - Best practices 220 | 221 | If you found this article helpful, feel free to share it and star the repo. If want to talk about developer education or developer-facing docs, feel free to reach out: 222 | - [jojab.dev](https://www.jojab.dev) 223 | - [GitHub](https://github.com/jablonskidev) 224 | - [Twitter](https://twitter.com/Jo_Jablonski) 225 | - [LinkedIn](https://www.linkedin.com/in/joanna-jablonski-14b9a7140/) 226 | -------------------------------------------------------------------------------- /page-structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jablonskidev/how-to-make-a-docs-site/c8251d9b85bdef76b0c04a0e58109c54ad510b77/page-structure.png --------------------------------------------------------------------------------