{"id":13567323,"url":"https://github.com/jamiebuilds/documentation-handbook","last_synced_at":"2026-02-14T11:03:04.610Z","repository":{"id":66094864,"uuid":"68658078","full_name":"jamiebuilds/documentation-handbook","owner":"jamiebuilds","description":"How to write high-quality friendly documentation that people want to read.","archived":false,"fork":false,"pushed_at":"2016-11-15T23:55:57.000Z","size":31,"stargazers_count":299,"open_issues_count":1,"forks_count":29,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-09-08T09:48:36.856Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamiebuilds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-09-20T00:29:40.000Z","updated_at":"2025-08-03T00:50:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"29bda03e-7c1d-42a4-b7b2-00748ce9de99","html_url":"https://github.com/jamiebuilds/documentation-handbook","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jamiebuilds/documentation-handbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Fdocumentation-handbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Fdocumentation-handbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Fdocumentation-handbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Fdocumentation-handbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamiebuilds","download_url":"https://codeload.github.com/jamiebuilds/documentation-handbook/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamiebuilds%2Fdocumentation-handbook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29443447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T10:51:12.367Z","status":"ssl_error","status_checked_at":"2026-02-14T10:50:52.088Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:02:28.460Z","updated_at":"2026-02-14T11:03:04.575Z","avatar_url":"https://github.com/jamiebuilds.png","language":null,"funding_links":[],"categories":["Misc","Development Tools"],"sub_categories":[],"readme":"# How to write high quality friendly documentation that people want to read\n\n## Translations\n\n\u003c!-- - [English](/README.md)\n\u003c!-- - [Afrikaans](/translations/af/README.md) --\u003e\n\u003c!-- - [العربية](/translations/ar/README.md) --\u003e\n\u003c!-- - [Català](/translations/ca/README.md) --\u003e\n\u003c!-- - [Čeština](/translations/cs/README.md) --\u003e\n\u003c!-- - [Danske](/translations/da/README.md) --\u003e\n\u003c!-- - [Deutsch](/translations/de/README.md) --\u003e\n\u003c!-- - [ελληνικά](/translations/el/README.md) --\u003e\n\u003c!-- - [Español](/translations/es-ES/README.md) --\u003e\n\u003c!-- - [Suomi](/translations/fi/README.md) --\u003e\n\u003c!-- - [Français](/translations/fr/README.md) --\u003e\n\u003c!-- - [עִברִית](/translations/he/README.md) --\u003e\n\u003c!-- - [Magyar](/translations/hu/README.md) --\u003e\n\u003c!-- - [Italiano](/translations/it/README.md) --\u003e\n\u003c!-- - [日本語](/translations/ja/README.md) --\u003e\n\u003c!-- - [한국어](/translations/ko/README.md) --\u003e\n\u003c!-- - [Norsk](/translations/no/README.md) --\u003e\n\u003c!-- - [Nederlands](/translations/nl/README.md) --\u003e\n\u003c!-- - [Português](/translations/pl/README.md) --\u003e\n\u003c!-- - [Português (Brasil)](/translations/pt-BR/README.md) --\u003e\n\u003c!-- - [Portugisisk](/translations/pt-PT/README.md) --\u003e\n\u003c!-- - [Română](/translations/ro/README.md) --\u003e\n- [Pусский](/translations/ru/README.md)\n\u003c!-- - [Српски језик (Ћирилица)](/translations/sr/README.md) --\u003e\n\u003c!-- - [Svenska](/translations/sv-SE/README.md) --\u003e\n\u003c!-- - [Türk](/translations/tr/README.md) --\u003e\n\u003c!-- - [Український](/translations/uk/README.md) --\u003e\n\u003c!-- - [Tiếng Việt](/translations/vi/README.md) --\u003e\n\u003c!-- - [中文](/translations/zh-CN/README.md) --\u003e\n\u003c!-- - [繁體中文](/translations/zh-TW/README.md) --\u003e\n\n**[Request another translation](https://github.com/thejameskyle/documentation-handbook/issues/new?title=Translation%20Request:%20[Please%20enter%20language%20here]\u0026body=I%20am%20able%20to%20translate%20this%20language%20[yes/no])**\n\n---\n\nFor the last few years I have written a lot of documentation for projects like\nBabel or Flow, blog posts, and guides such as these:\n\n- https://github.com/thejameskyle/the-super-tiny-compiler\n- https://github.com/thejameskyle/itsy-bitsy-data-structures\n- https://github.com/thejameskyle/babel-handbook\n\nI've tried to focus on the way that I write in order to make it more\napproachable and more useful to everyone. There are a number of things that I\nhave learned over the years that I believe makes for high-quality and friendly\ndocumentation.\n\n\u003e **Note:** Some of this only really applies when you are talking about things\n\u003e that require tons of documentation. Try to adapt this advice to fit what you\n\u003e are working on best.\n\nHere they are as one massive list:\n\n#### In general...\n\n- Keep a lighthearted friendly tone. Don't spend time trying to prove how smart\n  you are. Treat the reader as a close friend who doesn't have a lot of\n  knowledge about the topic but is very interested.\n- Don't assume prior knowledge about the topic. If you want to appeal to a\n  large audience (i.e. not a research paper) then you are going to have people\n  with very diverse backgrounds.\n- Don't use words like \"obviously\" or \"basically\", I promise you will never\n  *need* to. Just say what needs to be said in simple straight forward\n  language. Never ever talk down to people (both of those words do, as well as\n  others).\n- Don't use idioms. Speak using more formal terms that are well defined. This\n  makes it easier for non-native-english speakers and for translations to be\n  written. If you do, you won't just knock it out of the park, you'll do a\n  really good job.\n- Use words that are easier to understand and translate (i.e. \"list\" instead\n  of \"enumerate\"). Don't worry that you're being slightly more precise using a\n  bigger word, think about how it will sound to someone unfamiliar with the\n  topic.\n- Keep things brief. Avoid giant paragraphs, breaking them apart into multiple\n  paragraphs each with a clear point. If you are writing really long\n  paragraphs, it's most likely that you aren't doing a good job explaining what\n  you mean.\n- Link to other places in the documentation often ***but*** only for additional\n  information. Readers should not have to navigate through several pages to\n  find the information that they need about one specific thing. Just inline the\n  immediately relevant information and link off if they want to know more.\n- Reuse the same small set of examples as much as possible, keep presenting the\n  same problem and building on top of it. Don't make the user keep thinking\n  about new problems, people can only focus on so many things. If you need to\n  keep coming up with new examples, you haven't started in a good place, start\n  over and come up with a better one.\n\n#### When writing guides...\n\n- Use as many code/cli/etc examples as possible, *show* the reader what you\n  mean. This makes things far easier to translate and is generally much easier\n  to follow than walls of text. Even if you aren't going to discuss the code\n  directly it's good for giving context.\n- Use headings frequently. This breaks things up when reading and often it is\n  good for linking to specific information.\n- If writing with multiple pages, think about how a single page leads into the\n  next, point the user to the next page and make sure it follows naturally.\n- Gently introduce a guide before diving into technical details. This gives\n  context and readers are more likely to stay engaged longer.\n- Tell one story at a time. You can re-explain the same concepts from different\n  perspectives or for different use-cases.\n- Don't clutter explanations with overly detailed examples. You don't need to\n  implement a game of sudoku to explain how you might use your library with it.\n  Typically if you have to explain the backstory of an example then it is too\n  complicated and serves as a distraction from what you're teaching.\n- Don't be afraid of foo's and and bar's. Using them removes mental overhead,\n  it's explicitly saying to the reader \"don't worry about what this is, is\n  could be anything\"\n\n#### When writing api documentation...\n\n- Think about API docs like they are guides on how to use them. Type signatures\n  for input and output and a vague description isn't enough to be useful.\n- Add information explaining the purpose of a group of APIs before diving into\n  them. Also add any other relevant information or caveats. People are far more\n  likely to read it this way.\n- Use shared terminology with API names, examples, and explanations. Call\n  something a single name no matter where you are referring to it, and name\n  things\n- Don't try to solve real world scenarios in code examples if they become any\n  more complicated than the API already is. Do not implement algorithms, do not\n  add a bunch of noisy implementation details that doesn't aid the user.\n- Keep code examples extremely short. Your target should be ~3-5 lines of code,\n  every line past that is a count against you. Think hard about the examples\n  you are using.\n\n#### Absolutely...\n\n- Never use terms that are offensive to any group. There will never be a good\n  reason to.\n- Do not use gendered terms. Pronouns like he/she/her/him and gendered terms\n  like actress/actor/waiter/waitress should all be thrown out and you should\n  avoid using any terms or phrases that don't necessary refer directly to\n  gender but have gendered connotations. For example, words \"pretty\", \"curvy\",\n  \"moody\", or \"bossy\" all refer to women far more often than they do men.\n- Avoid examples using people. You end up sounding like you're talking to\n  children and it's easy to create examples that place one group of people over\n  another (i.e. \"Susan went to her project manager Tim...\"). So as a more\n  generalized rule, use examples that don't involve people.\n- Follow other guidelines outlined in documents like the\n  [Contributors Covenant](http://contributor-covenant.org/).\n\n---\n\nThis is a living guide for myself and others as I learn more about writing\ndocumentation. I hope it is helpful to others in its current state. If you have\nany suggestions, feel free to open an issue or pull request on GitHub and let\nme know.\n\nHave fun writing!\n\n---\n\n[![cc-by-4.0](https://licensebuttons.net/l/by/4.0/80x15.png)](http://creativecommons.org/licenses/by/4.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamiebuilds%2Fdocumentation-handbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamiebuilds%2Fdocumentation-handbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamiebuilds%2Fdocumentation-handbook/lists"}