8 ms·
> If your documentation is a directory full of files on GitHub, I close the tab. With GitHub Pages, Read the Docs, and other places to host generated documentat
by dominicrodger 13y ago
> If your documentation is a directory full of files on GitHub, I close the tab. With GitHub Pages, Read the Docs, and other places to host generated documentation for free, not making an effort is unforgivable.
He's not arguing against GitHub pages - he's arguing against just linking to a file/folder in your GitHub repository and thinking you're done (e.g. https://github.com/<org>/<project>/docs https://github.com/<org>/<project>/docs).
- Gigablah 13y agoGitHub renders markdown files. So the difference between clicking on navigation links in a documentation website and clicking on markdown files in a GitHub docs folder is... the CSS theme.
- cobralibre 13y agoAs I see it, the author of TFA is simply offering some heuristics for judging whether or not he's going to have a hard or an easy time working with a project's documentation. So in this view, presenting documentation using a structure that is specifically intended for documentation is taken as an indicator of care and attention to detail. I wouldn't say that he's arguing that a directory full of files isn't functionally equivalent or isn't useful. (Personally, out here in the real world, I'll put up with all sorts of limitations — even a complete lack of documentation — if somebody else's existing code solves a problem that I have.)