5 ms·
I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs
by simonw 5y ago
I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons:
1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work
2. This means it can be enforced during code review: if a developer forgets to update the docs they can be reminded before they land their PR
3. This also provides a version history for the documentation which is synchronized with the code history. This is really useful when looking at history and trying to figure out what changed when.
4. This also works great with branches, PRs and releases. New features can have their documentation developed alongside the code in a branch, which makes it easier to understand a proposed change. If your software is deployed in multiple places as multiple versions (or even just staging vs production) you have a way to view the correct documentation for each individual deployment.
5. Added together, all of this builds trust. A common problem I've seen with internal documentation is that no-one trusts it to be up-to-date. Making it part of the regular code development lifecycle can fix this.
6. If you do this, you can write automated tests that enforce aspects of your documentation! I call these documentation unit tests, and wrote about them here: https://simonwillison.net/2018/Jul/28/documentation-unit-tests/ https://simonwillison.net/2018/Jul/28/documentation-unit-tes... - even something as simple as a test that fails if a new API endpoint isn't mentioned in a markdown file using simple string matching can ensure no-one forgets about the docs when they add a new feature.
- Noumenon72 5y agoHow do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.
- simonw 5y agoI use documentation systems that publish the documentation from the repo to a website. Most of my projects use Sphinx and reStructuredText for this, but I recently tried MyST (Markdown for Sphinx) and I like that a lot. Some examples: - https://docs.datasette.io https://docs.datasette.io serves documentation from https://github.com/simonw/datasette/tree/main/docs https://github.com/simonw/datasette/tree/main/docs - which has documentation unit tests here: https://github.com/simonw/datasette/blob/main/tests/test_docs.py https://github.com/simonw/datasette/blob/main/tests/test_doc... - https://sqlite-utils.datasette.io/ https://sqlite-utils.datasette.io/ serves from https://github.com/simonw/sqlite-utils/tree/main/docs https://github.com/simonw/sqlite-utils/tree/main/docs - unit tests here: https://github.com/simonw/sqlite-utils/blob/main/tests/test_docs.py https://github.com/simonw/sqlite-utils/blob/main/tests/test_... - https://django-sql-dashboard.datasette.io/ https://django-sql-dashboard.datasette.io/ serves from markdown in https://github.com/simonw/django-sql-dashboard/tree/main/docs https://github.com/simonw/django-sql-dashboard/tree/main/doc... - I don't have documentation unit tests for that yet Those three are all hosted on https://www.readthedocs.org https://www.readthedocs.org but I've also used this trick on web app projects that host their own documentation deployed as part of the build process.
- petepete 5y agoThis is definitely the best approach in my opinion, providing the people writing the docs are capable of contributing directly. One of my projects[0] builds and deploys a static documentation site[1] on every push to master. The static site generator (Nanoc, in this case) imports the library and uses it to publish its own documentation. All the examples are snippets of code[2] that are both displayed as-is and eval'd into the final output. The guide can never be out of sync with the library. [0] https://github.com/dfe-digital/govuk_design_system_formbuilder/ https://github.com/dfe-digital/govuk_design_system_formbuild... [1] https://govuk-form-builder.netlify.app/ https://govuk-form-builder.netlify.app/ [2] https://github.com/DFE-Digital/govuk_design_system_formbuilder/blob/master/guide/lib/examples/text_input.rb https://github.com/DFE-Digital/govuk_design_system_formbuild...
- zelphirkalt 5y agoThis is a good approach and reStructuredText well suited for technical documentation. The only downside I see in reST is, that it is mostly only readable from the standard implementation in Python, which is a custom parser, not a portable grammar for other languages to implement in any parser tool / library. There are some libraries for parsing it, but last I checked those were incomplete. Emacs org-mode would be a great candidate as well, for things like runnable code inside the documentation as examples and export to many other formats and nice tooling for viewing the files. Unfortunately many git hosts do not support it well and render crappily. I would recommend against switching to a non-standard Markdown dialect. Why switch away from reST, which offers all of the things nessecary for a good technical documentation, to some Markdown dialect, which has many important features only bolted on? That said, one thing I noticed happening with this approach is, that people think "Oh, I have my documentation in my comments of the code! I don't need to write anything else!" And then I end up reading documentation like: "def get_a(): ..." Docstring or comment: "Get a." Wow, thanks, how helpful! In short: There is no simple way to have good documentation, except for writing good documentation. Docstrings probably will not be sufficient, unless you write whole novels in your docstrings. A good documentation needs usage examples and rationale of why something was done in a specific way, what kind of gotchas there are and probably other stuff, that does not come to mind right now.
- klohto 5y agoStatic site generated from the repo. Can be hosted locally or online. Github pages are usually leveraged for this usecase
- navotgil 5y agoYou can use the CI to publish you md files with tools like https://docusaurus.io/ https://docusaurus.io/
- brox 5y agoIf using Django there are tools like django-docs (https://django-docs.readthedocs.io/en/latest/ https://django-docs.readthedocs.io/en/latest/) and the recently released django-sphinx-view (https://noumenal.es/django-sphinx-view/ https://noumenal.es/django-sphinx-view/).
- zelphirkalt 5y agoIf you write your documentation in Emacs org-mode, you could use include [1] to include files on other levels of your repository and then you could export it all to a markdown file for people, who do not know about org-mode and Emacs. This would make documentation anywhere in the repository discoverable / automatically included in your resulting documentation file. [1] https://orgmode.org/manual/Include-Files.html https://orgmode.org/manual/Include-Files.html
- aidos 5y agoIn the PostgreSQL codebase they have readmes scattered about and it’s great to jump into some subfolder and get the details you need in the right context.
- iamEAP 5y agoCheck out Backstage, and in particular, TechDocs: https://backstage.io/docs/features/techdocs/techdocs-overview https://backstage.io/docs/features/techdocs/techdocs-overvie...
- Zababa 5y agoThe webpage can be generated from markdown files which can be in the repo.
- forgotmypw17 5y agoWrite the documentation as text files. Include hashtags for topics, e.g. #authentication, #language, or #netscape. Use the text file indexing and management system to browse and update the documentation.
- daurnimator 5y agoNone of this works if the programmer isn't the same person that writes the docs. e.g. if you have a copy-writer come along and write/update the docs before each release, then its not captured in the same commit/branch/etc.
- simonw 5y agoThat can still work, in a couple of ways. You can have the programmer write bad documentation and file an issue for it to be improved. You can then enforce that releases don't go out until those issues have been resolved by the copywriter. You can also implement new features in a branch with multiple authors. The branch doesn't get merged until the documentation is in good shape.
- prepend 5y agoIt still works ok, just not as nicely. The copy editor updates the repo and while their changes won’t be in the same commit, they should be nearby. So you still get the benefit of docs history, and being in the same place.
- skeeter2020 5y agoI think you could also make a case that if you've adopted these strict documentation requirements you don't decouple the functional commits from the documentation commits. Your copy editor could work in the same branch as the code changes and then you only approve the PR when the documentation is at the same level of QA as the code. Otherwise a fear separate commits or branches is the thin edge of the wedge.
- monocasa 5y agoSure it does, developers work with domain experts on features all the time. Perhaps you had SDETs adding some test infrastructure, or designers adding assets and layout information. Either you can have feature branches, or stubs/scaffolding for CI. I've seen both work. The biggest issue I've see is management and product who seem allergic to the actual repos for some reason.
- dllthomas 5y ago> a test that fails if a new API endpoint isn't mentioned [...] That's a great idea. A related thought I had was testing assertions about architecture by looking at the graph of imports or calls. From your blog post, > if a change doesn’t update the relevant documentation, point that out in your review! What you get at but don't seem to state explicitly is that finding the relevant documentation is hard, for both the author and reviewer. Finding any relevant documentation should be easy, but ideally we're finding all relevant documentation, and we need to be reaching sufficient confidence that we're missing little enough that we're able to hold back entropy enough to keep the docs useful. Your tools address this for some cases! Doctest addresses this for other cases. From TFA here, it sounds like Swimm.io tries to address this for more cases (my gut says the article oversells it but I intend to look more closely). To get further, an idea I've been toying with is to treat claims (implicit or explicit) in documentation as requiring citation, pointing not at sources but at tests. Ideally the test runner, when a test fails, can then surface all references to that test. In addition to highlighting portions of the docs that may need to change, this seems likely to also provide crucial context when fixing the code and/or the test.
- tanaypingalkar 5y agoIs there any lib/way that automatically generate doc for api/endpoint. I think it is possible to create such generator for graphql api.
- wmiel 5y agoYou can checkout Swagger and OpenAPI, there are libraries to annotate the endpoints in the code and then generate interactive docs out of that.
- chupchap 5y ago> I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: I have a small disagreement on that. I always feel documentation should be outside of code as it might need to be reviewed by people who do not have access access to the code base. Then there are also the "Why are we doing this" part of documentation that is difficult to mark out in code. Documenting in code is great for addressing "how are we doing this" part IMO.
- simonw 5y agoThe docs may live in the repo but they should definitely be published somewhere that non-GitHub users in the organization can view. The higher level strategic stuff can absolutely live elsewhere - in my experience Google Docs or some kind of company-wide wiki often come into play here.
- chupchap 5y agoI was thinking more of an enterprise situation where multiple systems might be working together as part of a process. The code for each system might be in different repos in which case the documentation would also be broken. In such a context having the unit level documentation in the repo makes sense, but the overarching process documentation that is constantly evolving and referenced by multiple teams cannot be part of this repo.
- zie 5y agoI assume the OP meant, or at least how I took it and implement it, it can be in a dir called docs/ off the root of the tree. It doesn't have to be literally scattered about in the actual source, just in the same repo. Though there are reasons to do both(some docs from the source itself, and some from docs/) but that's a different debate.