Open alejandrosame opened 1 year ago
This issue has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-08-03-documentation-team-meeting-notes-69/31263/1
This issue has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-08-17-documentation-team-meeting-notes-73/31853/1
Regarding the hooks documentation, we discussed with the @NixOS/documentation-team a while ago whether it would make sense to extract the documentation comments and strip them from the build to avoid mass rebuilds when editing them. It needs some research whether it's meaningful, and @roberth suggested that in the meantime we could just add .md
files next to the hooks.
This issue has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-08-23-documentation-team-meeting-notes-75/32142/1
Problem
The Python chapter in nixpkgs manual is hard to navigate and use. The Documentation team has agreed to follow the Diátaxis framework as a methodology to improve our documentation.
Diátaxis
defines what constitutes as reference, how-to and explanation material.With this context, it is clear that the Python section mixes all these types of contents and does not stick to a unified style. The next subsection shows the outline in
unstable
(https://github.com/NixOS/nixpkgs/commit/3acb5c4264c490e7714d503c7166a3fde0c51324) with an assessment of the type of documentation that is predominant in a given heading.Tagged outline
User Guide
How-to
Reference
Reference
Reference
Reference
How-to
Reference
How-to
Explanation
Explanation
How-to
How-to
FAQ
How-to
How-to
How-to
How-to
Explanation
How-to
How-to
How-to
How-to
How-to
Reference?
Contributing
How-to
, guidelines, policyPackage set maintenance
Explanation
andHow-to
How-to
and guidelinesCPython Update Schedule
Explanation
, policyProposal
The Python section in the nixpkgs manual should stick to
Reference
content. In order to achieve this goal incrementally, the following course of action is proposed:non-Reference
content out of theReference
subsection. https://github.com/NixOS/nixpkgs/pull/247117Reference
subsection to the top of the Python chapter. https://github.com/NixOS/nixpkgs/pull/247117After taking these actions, the Python section will have two clearly distinct content blocks: the reference section, and content that is further from being reference material. These changes should keep content in the current single Markdown file.
At this point, it should be easier to proceed per individual section:
Explanation
/How-to
section that is missing fromReference
.Explanation
/How-to
section and move it accordingly.Related