Posted by ibobev 1 day ago
An example:
- source: https://github.com/eslint/eslint/blob/main/docs/src/rules/no...
- rendered: https://eslint.org/docs/latest/rules/no-control-regex
This is a very simple example, you can see how the code blocks are highlighted better and slightly interactive.
Exactly, I use Sphinx to make a nice website from the markdown sources (although it doesn't have to be markdown). That includes generating a full API reference page from all the docstrings.
Docs being updated to reflect the code can then (and must, IMO) be a blocking constraint on all pull requests.
https://github.com/super-productivity/super-productivity/blo...
The generic-ness of the wiki wasn't an issue for me as I only intended on using it as a temporary measure to build up the bulk of the content and coordinate with the main dev on finding a balance between the flashy website with its guides and the less flashy docs. gh-pages is the obvious next step of course.
1. Docs that are naturally versioned with the code, like API doc or a design doc, might well go in the code repos. (I'm personally a big fan of API docs embedded in comment chunks right above the respective implementation chunk, but a separate Markdown or SVG file, or other format, also works.)
2. Everything else, one of the top priorities is to minimize friction to someone who has the information capturing it such that it can be found by someone else later, so put it in the very low-friction wiki (or an issue/task comment).
3. Have a lightweight way of cross-linking things between these locations, that everyone knows, so info is more likely to be found later.
This still applies even if you feed everything into AI now.
I've been trying for years to get the contents indexed, accessible to search engines or even AI. When I started, no wiki was ever indexed but it seems GitHub backed off a bit since then. Still, there's a bunch that is still not indexed for various reasons with valuable data in them.
I do agree, most users should look into docs instead.
Of course someone will object to doc-only updates not getting review. That person is now on the hook for reviewing all doc updates after you merge them. It's the exact same thing you were doing before - they only objected when it got formalised.