add extension to display contributors on documents

[fricklerhandwerk]

[friedow]

Why do we need this feature? I don't see value in displaying this information.

[fricklerhandwerk]

The follow-up #1261 (adding more annotations) closes the long-standing issue #543, which touches upon several related subjects that keep popping up:

• We always had an issue with finding an editorial voice. Making authorship evident ameliorates it, because attribution allows readers to map the voice to the author and thus "correct" for the tone
• We had several discussion over the years about appreciation of past contributions, including the donation of the original collection of material. Clearly displaying authorship addresses that, credit is given where due.

But actually I'm confused about the question, because how can giving credit not be something we want unconditionally?

• Those pieces of writing don't appear from thin air. Many of those tutorials were weeks of work by multiple people, not counting ongoing maintenance. Why not show how the sausage is made?
• Public credit is a viable way to attract high-quality contributions.
• It's non-negotiable in, for example, academia and the film industry. (And the link to commit history with the full record is rather weak; using that for figuring out who did the load-bearing work isn't all that simple.)
• The Nix repo, too, started crediting notable contributions in their release notes already a while ago.

I could continue...

[friedow]

My opinion is that people come to nix.dev to read about nix. For that, the information who authored or changed a page is not necessary. Thus, I'd not show it. If you want to know who changed content, you can always refer to the versioning information on github. Might be a too puristic / simplistic point of view.

All of this is just my personal take. I also don't mind this being merged if others really want this.

[hsjobeki]

I don't have a complicated opinion on this feature. adding is fine, if everyone maintains it

My only ask: it should be placed after the content.

We have enough introductions and tables to scroll over until you reach an answer for your problem.

Does the reader want reach out to people after the have not understood things or do they need to know who wrote it beforehand?
Credibility is nice, but i think its a second class concern that should be placed at the bottom of an article.
First class is answering questions and resolving user problems.

That should be reflected by order.

[fricklerhandwerk]

Done straightforward, it doesn't really work:

One thing I can imagine is moving it to the footer:

Or without the box:

It would be uglier in the implementation.

• Would additionally need a template extension for the footer
• One can't naturally process YAML frontmatter with structured data in Sphinx because of how the stack works, you have to parse it manually. Therefore ideally the annotation would stay in the document as is, which may make it slightly confusing as to why it renders not where it lives in the source
• Styling it consistently with the surrounding footer requires stripping the default style in a targeted fashion by "magically knowing" it (it will shift around between Sphinx updates); by default the style looks very off, with margins and such.

Though on semantic grounds, while I expected that sort of request, I'm still a bit disappointed.

Does the reader want reach out to people after the have not understood things

No, that misses the point. Every news paper article states the author in the beginning, among others, exactly for the voice reason: "Now comes a text by this person". People first and all... In any case, many authors are long gone; if anything the reader will reach out to maintainers.

We have enough introductions and tables to scroll over until you reach an answer for your problem.

I agree, and the Nix language tutorial is a particularly bad case because it was written in a time and still exists in a context where many people come with particular expectations, and those need to be dismantled before the conveying of ideas becomes likely to succeed. But some of that boilerplate can be set off visually with the same technique as proposed in this PR. For example, make the prerequisites a structured annotation and render it differently (then we can even draw a tech tree programmatically!), for instance more compact. Then it will be evident where the main content starts.

First class is answering questions and resolving user problems.

Yes, and we're doing that in the guides and troubleshooting sections. Tutorials and explanations seem to be of a different quality, since they are narrative in nature and apparently in fact have a small number of people shaping it. Your comment does enlighten me on the follow-up -- probably we shouldn't add the authors box to best practices and other such facts collections, since those are clearly mechanistic.

[hsjobeki]

Given the outcome of the discussion LGTM from my side.

We can revisit the styling if it turns out to be hindering the reader flow.