{"id":16001492,"url":"https://github.com/jdno/useful-docs","last_synced_at":"2026-02-13T17:03:14.175Z","repository":{"id":68782462,"uuid":"114925958","full_name":"jdno/useful-docs","owner":"jdno","description":"Useful Documentation proposes a structure for documentation in modern software projects. It is designed to capture the most important information in a process that is transparent, collaborative and extensible.","archived":false,"fork":false,"pushed_at":"2018-01-10T15:17:33.000Z","size":3,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-27T06:47:10.702Z","etag":null,"topics":["adr","documentation","requirements"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdno.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-20T19:58:54.000Z","updated_at":"2018-01-10T15:18:18.000Z","dependencies_parsed_at":"2023-03-01T22:46:06.355Z","dependency_job_id":null,"html_url":"https://github.com/jdno/useful-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jdno/useful-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdno%2Fuseful-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdno%2Fuseful-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdno%2Fuseful-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdno%2Fuseful-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdno","download_url":"https://codeload.github.com/jdno/useful-docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdno%2Fuseful-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29412670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T06:24:03.484Z","status":"ssl_error","status_checked_at":"2026-02-13T06:23:12.830Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["adr","documentation","requirements"],"created_at":"2024-10-08T09:43:50.980Z","updated_at":"2026-02-13T17:03:14.158Z","avatar_url":"https://github.com/jdno.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Useful Documentation for Software Projects\n\nGood documentation is important in any software project. But for many different\nreasons, most projects don't have documentation. It is hard to figure out what\nto document, where to do it and how to keep it up-to-date. Making time to figure\nthese things out is often not possible within the scope of a project, which is\nwhere _Useful Documentation_ comes in.\n\nThis project proposes a structure for documentation in modern software projects.\nIt is designed to capture the most important information in a process that is\ntransparent, collaborative and extensible.\n\n## Document Types\n\nProject documentation is split into two categories: **decisions** and\n**requirements**. Decisions document the _why_, and **requirements** document\nthe _what_. The _how_ is documented by the code itself, or if that is\ninsufficient through documentation in the code.\n\n### Decisions\n\nThe outline for decisions is based on [Architecture Decision Records][adr]. It\ncaptures the context for a decision as well as its outcome in a brief format.\nFor decisions, the following rules apply:\n\n- Decisions are numbered sequentially and monotonically\n- Decisions are never deleted but _superseded_ by new ones\n\nFor more information on ADRs, check out the original blog post. For examples,\ntake a look at the [GOV.UK](https://github.com/alphagov) repositories, where\nADRs are widely used.\n\n### Requirements\n\nIt is important to plan a little bit ahead when implementing new features, and\nrequirements documents are a standard way to do this. They capture the goal of a\nnew feature, the steps it takes to implement it as well as any questions or\nconcerns a new feature might introduce.\n\nThe structure of the requirements document is inspired by the [requirements document](https://confluence.atlassian.com/doc/blog/2015/08/how-to-document-product-requirements-in-confluence)\nin [Confluence](https://www.atlassian.com/software/confluence).\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n[adr]: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdno%2Fuseful-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdno%2Fuseful-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdno%2Fuseful-docs/lists"}