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

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

As 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.)

Pretty sure it's a typo (speaking as a Brit).

In the mother of all pedantic pull requests, I've created https://github.com/python/pythondotorg/pull/77

It's now documented and everything: https://docs.djangoproject.com/en/dev/topics/migrations/#upg...

Doesn't this mean people can track whether you've read an email by including some kind of unique identifier in the image path? If not, how could this possibly work?

People have been doing that for a while -- it's very common to put a 1 pixel by 1 pixel image in an email as a tracking bug.

Likewise - I did this as part of a hackathon earlier this year - thoroughly enjoyed seeing how all the pieces fitted together.

See also https://news.ycombinator.com/item?id=4970707

I'm pretty sure they're just markers telling you what the code is an example of, so they get out of your way when you hover over the code.

You're correct, thanks for the answer here.

Feedback has been hot and cool on them, still trying to decide if they are worth it or not.

I'm not really seeing why I would want the label of the section in question hidden when I'm dealing with it, and at least for me there's not really a parity between 'dealing with' and 'hovering over with my cursor' anyway, unless I'm copying the text. The bright orange color and the constant flashing on/off just adds visual noise and makes it difficult to really read the labels anyway, imo.

Having them pop out of existence is jarring; maybe have them fade to near-invisible.

Btw, Does not fade away in IE8 with hover.

IE8 can't do anything fancy.

We use it to mean practising how we handle bad things, such as unexpected server failures, which seems to me a reasonable appropriation of the term.

Thanks for the write-up - interesting read.

Out of interest, how do you catch and block all POST requests when the site's in read-only mode without duplicating code? Not sure if you use CBVs at Lanyrd - if so, do you use a common mixin? If not, how?

We have some common Django middleware used for every dynamic page on the site which deals with that (among other things). We also strip cookies at the Varnish layer.

See also "Entmoot" from Lord of the Rings.