Credit article authors

[fricklerhandwerk]

Observations It's not evident for readers – and tedious to figure out – who wrote a particular article (and similarly, who maintains it).

Problem Authors are not credited appropriately. This is a particular problem now that nix.dev is transferred to the NixOS Foundation, while @domenkozar provided the bulk of the original material. We also expect many more tutorial and guide authors to make new contributions, and those should be credited as well.

Approaches

• provide links to GitHub's blame view or contributors listing
  • the most accurate, requires least amount of maintenance once set up
  • probably more tricky to set up, may require custom code
• use Sphinx's codeauthor directive in documents
  • allows for more control, can highlight the original author(s) of a document (who usually account for the largest part of its contents over its lifetime)
• use CODEOWNERS to help communicating with maintainers
  • this is more interesting for the contribution and review process than for assigning credit

Priorities

Add :+1: to issues you find important.

[zmitchell]

Discussed in documentation team meeting

Order of priority:

• Link to source document
• Either author by-line or CODEOWNERS link
• Git-blame view and other fancier forms of reporting activity

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-06-documentation-team-meeting-notes-61/30087/1

[yukiisbored]

I'm assigning myself to remind me to look into codeauthor and other potential solutions in the Sphinx ecosystem.