4 ms·

How 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 rep

How 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 ago
I 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 ago
  This 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 ago
  This 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.
  - simonw 5y ago
    "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?" Honestly, the main reason is that I've encountered developers who have an almost alergic reaction to rST - they genuinely hate writing in it, and will be deterred from writing documentation if they have to figure it out. Custom Markdown flavours are more likely to get buy-in.
    - zelphirkalt 5y ago
      I see. Sometimes it seems, that there is some kind of animosity towards any non-markdown format, as if markdown was the one and only. Ha, so far from it ... But everything else must be eradicated with some kind of hostility, it seems. The people exhibiting this kind of behavior often do not know other formats well, nor have they bothered to use another format for a while to find out about what it can express. It is as if children do not want to give up on their favorite toy, even when there is need for something more capable, to write technical documentation. I have used Markdown, Pandoc Markdown, probably Github Markdown, probably other dialects of Markdown and I kept missing features for writing documents. I have written a thesis in rST and it worked very well, even though Pandoc at the time did not understand citations and arbitrary document internal references (both of which standard markdown does not have) in rST well enough. I had to write my own pre-parser for it. I could not have written that thesis in some markdown dialect incapable of expressing things, that one simply needs in academic writing. There was Pandoc Markdown, but it felt bolted-on and rather ad-hoc in comparison to rST, which brought all the things out of the box. I remember also looking at AsciiDoc at some point. Not sure, why I did not choose it. Then I discovered Org-mode. It has been a journey to uncover more and more of org-mode capabilities. Org-mode does not suffer from the same eco-system split up as markdown does. It does not have this bolted on feeling, that many markdown dialects leave me with. It usually has everything I need. In fact, I have written technical documents in it as well and have discovered things like literate programming. The tooling in Emacs is so good, it is really nice to work with org files. Good, that I can still export to primitive markdown, for anyone not knowledgeable in org-mode. Even though org files are merely human-readable plain text documents. It is unfortunate, that VCS hosts are unable to render them properly. I would really dislike going back to markdown only. It feels so limiting to me now, that I have developed an aversion against writing documentation in an unsuitable format like markdown (talking standard markdown, probably commonmark). If there is already markdown only documentation, then well OK, I guess I can write it, although it surely will not feel great.
klohto 5y ago
Static site generated from the repo. Can be hosted locally or online. Github pages are usually leveraged for this usecase
- navotgil 5y ago
  You can use the CI to publish you md files with tools like https://docusaurus.io/ https://docusaurus.io/
- brox 5y ago
  If 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 ago
If 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 ago
In 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 ago
Check out Backstage, and in particular, TechDocs: https://backstage.io/docs/features/techdocs/techdocs-overview https://backstage.io/docs/features/techdocs/techdocs-overvie...
Zababa 5y ago
The webpage can be generated from markdown files which can be in the repo.
forgotmypw17 5y ago
Write 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.

simonw 5y ago

I 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 ago
This 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 ago
This 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.
- simonw 5y ago
  "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?" Honestly, the main reason is that I've encountered developers who have an almost alergic reaction to rST - they genuinely hate writing in it, and will be deterred from writing documentation if they have to figure it out. Custom Markdown flavours are more likely to get buy-in.
  - zelphirkalt 5y ago
    I see. Sometimes it seems, that there is some kind of animosity towards any non-markdown format, as if markdown was the one and only. Ha, so far from it ... But everything else must be eradicated with some kind of hostility, it seems. The people exhibiting this kind of behavior often do not know other formats well, nor have they bothered to use another format for a while to find out about what it can express. It is as if children do not want to give up on their favorite toy, even when there is need for something more capable, to write technical documentation. I have used Markdown, Pandoc Markdown, probably Github Markdown, probably other dialects of Markdown and I kept missing features for writing documents. I have written a thesis in rST and it worked very well, even though Pandoc at the time did not understand citations and arbitrary document internal references (both of which standard markdown does not have) in rST well enough. I had to write my own pre-parser for it. I could not have written that thesis in some markdown dialect incapable of expressing things, that one simply needs in academic writing. There was Pandoc Markdown, but it felt bolted-on and rather ad-hoc in comparison to rST, which brought all the things out of the box. I remember also looking at AsciiDoc at some point. Not sure, why I did not choose it. Then I discovered Org-mode. It has been a journey to uncover more and more of org-mode capabilities. Org-mode does not suffer from the same eco-system split up as markdown does. It does not have this bolted on feeling, that many markdown dialects leave me with. It usually has everything I need. In fact, I have written technical documents in it as well and have discovered things like literate programming. The tooling in Emacs is so good, it is really nice to work with org files. Good, that I can still export to primitive markdown, for anyone not knowledgeable in org-mode. Even though org files are merely human-readable plain text documents. It is unfortunate, that VCS hosts are unable to render them properly. I would really dislike going back to markdown only. It feels so limiting to me now, that I have developed an aversion against writing documentation in an unsuitable format like markdown (talking standard markdown, probably commonmark). If there is already markdown only documentation, then well OK, I guess I can write it, although it surely will not feel great.

klohto 5y ago

Static site generated from the repo. Can be hosted locally or online. Github pages are usually leveraged for this usecase

navotgil 5y ago
You can use the CI to publish you md files with tools like https://docusaurus.io/ https://docusaurus.io/
brox 5y ago
If 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 ago

If 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 ago

In 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 ago

Check out Backstage, and in particular, TechDocs: https://backstage.io/docs/features/techdocs/techdocs-overview https://backstage.io/docs/features/techdocs/techdocs-overvie...

Zababa 5y ago

The webpage can be generated from markdown files which can be in the repo.

forgotmypw17 5y ago

Write 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.