Hacker News new | ask | show | jobs
by shakna 144 days ago
How many, many times has a project said, "Don't use, internal only", only for it to become an industry-wide common "trick"?

Saying "here be dragons" is not enough to discourage people whose job it is to be creative.

1 comments

That's the bad kind of lazy.

It is advantageous to format, interlink, and create a table of contents for documentation. I doubt anyone would advocate for removing the Makefile and conf.py from /Doc.

That a document describes something internal does not mean that it should be excluded from the docs.

Is there a consistent standard for whether something is internal or external to the CPython project? Aren't there already internal things documented in /Doc? Should they be removed from the docs build then? Or moved to an internal folder with a DRY additional toctree?