[RFC 0064] New Documentation Format for nixpkgs and NixOS #64
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,202 @@ | ||
| --- | ||
| feature: documentation-format | ||
| start-date: 2019-12-31 | ||
| author: Silvan Mosberger (infinisil) | ||
| co-authors: (find a buddy later to help out with the RFC) | ||
| shepherd-team: @domenkozar, @asymmetric, @alyssais, @jtojnar | ||
| shepherd-leader: @domenkozar | ||
| related-issues: (will contain links to implementation PRs) | ||
| --- | ||
|
|
||
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| Many people from the Nix community are interested in evaluating alternatives to DocBook as the documentation format for nixpkgs/NixOS. | ||
| Through the process of this RFC, a potentially new doc format will be decided. | ||
|
|
||
| # Motivation | ||
| [motivation]: #motivation | ||
|
|
||
| The current doc format for nixpkgs (including NixOS) is DocBook, which has seen a lot of criticism over the years. | ||
| With a more approachable and well-known documentation format we expect to have more doc contributions from more people. | ||
| This should improve our docs to be more up-to-date and complete. | ||
|
|
||
| # Detailed design | ||
| [design]: #detailed-design | ||
|
|
||
| The process for determining the doc format is as follows: | ||
| - A set of requirements for the doc format is decided through the RFC discussion | ||
| - Doc format candidates are collected and evaluated to see if they fulfil the requirements. This should include a small demonstration | ||
| - A short objective overview of each valid candidate format is written, along with their advantages/disadvantages | ||
| - A [Discourse](https://discourse.nixos.org/) post is created with these overviews, along with a poll such that people can vote on the formats they prefer. This poll will be open to the whole community and should be advertised as such | ||
| - With the result of the poll as an input, the shepherd team decides on a doc format to be used. This decision is added to the RFC, after which it is merged. | ||
| - People are then free to work towards that new documentation format and the committers of nixpkgs must not oppose these efforts due to the format choice | ||
|
|
||
| ## Poll | ||
|
There was a problem hiding this comment. I don’t like the poll idea. It’s too easy to vote for your favourite documentation format without considering the implications for our use case in Nixpkgs, which the most popular format might not be suited for. It’s difficult to reasonably argue this without mentioning specific formats — I think it’s unreasonable to believe that formats and decision-making processes are unrelated. I think we all know which format is going to win a popularity contest, but that doesn’t mean it’s the best choice for Nixpkgs. There was a problem hiding this comment. Summarizing from the discussion we had on IRC:
|
||
|
|
||
| Since documentation needs to be written and read by the many people from the community, we should incorporate them as possible into this important decision. Discussions in RFCs aren't optimal for this, since not many people are willing to comment, meaning the few people with the strongest opinion will be the main participants, in addition to GitHub's comment section being very annoying to navigate. Because of this, a public poll on Discourse is held instead, allowing many people to easily give their preferences. | ||
|
|
||
| The poll is of the following form: | ||
| - Multiple-choice, allowing people to select all formats they agree with | ||
| - Results are only shown when the poll is closed for it to not be influenced by non-final tallies | ||
|
There was a problem hiding this comment. Can the person who creates the poll see the tallies before-hand? If so, it would be good if the person who opens the poll explicitly discloses this in the conversation. I'm also OK with removing the "secret-tally" requirement, as I'm not convinced it actually influences people's opinions as much, in this case - especially in a multiple-choice poll. |
||
| - Answers can be changed while the poll is still active, allowing people to discuss about formats and change their opinion (this is not optional in Discourse) | ||
| - It runs for 1 month to give enough time for less-active people to see it | ||
|
There was a problem hiding this comment. I think 1 month is not enough for such a massive (and controversial change). I propose 2 months. |
||
| - Who voted for which options is made public (Only possible with bar chart in Discourse) TODO: Do we want this or not? Why would we? | ||
|
There was a problem hiding this comment. I think it can be useful to know where people stand (as there will surely be people who will vote without participating in the discussion) and to know whom to ask for help. And this is not one of those controversial or deeply personal topics that I think warrant anonimity honestly. It's a documentation format! 😂 |
||
|
|
||
|
There was a problem hiding this comment. Should we allow for people to vote on all options, or should we restrict that as basically an "I don't care" and not count the vote at all? I think it's still valuable to tally in those people who don't care, but who still took the effort to vote - it's still a sign of participation in the community. |
||
| ## Requirements | ||
|
|
||
| - Can be converted to HTML and man pages | ||
| - Cross-file references for being able to link to options from anywhere | ||
| - Ability to create link anchors to most places such that we can link to e.g. paragraphs | ||
| - Widespread editor integration featuring at least highlighting and preferably live-view | ||
|
There was a problem hiding this comment. Live-view is kind of a high-bar in my opinion, e.g. vim doesn't really have Markdown live-view AFAIK - and that's for the most popular markup format. I suggest we remove it from the requirements (also because "preferably" doesn't really make sense in this section if we interpret Requirements strictly) and move it to Nice-to-have's. There was a problem hiding this comment. I don't think that we should decide that based on the limits of certain editors. If vim doesn't offer live-view feature, then let's check editors that do. Getting instant feedback when doing any work really reduces the time needed to get something done and since documentation is already such a pain to write, I think this is key to getting more contributions. Most formats offer live preview via a plugin. There was a problem hiding this comment.
What do you mean by that? I think a format/feature that is not well supported by Vim is, realistically, not a good choice for a requirements section - unless we plan on implementing it ourselves. That's why, incidentally, I think org-mode doesn't belong to this list, as much as I like it. |
||
| - Good error detection in toolchain and editors, e.g. with a fast and good processor | ||
| - Is decently fast to fully generate, in the range of 10 seconds for the full documentation on an average machine | ||
|
There was a problem hiding this comment.
There was a problem hiding this comment. Nice, what do you mean by the last point though? That we don't need to write too many customizations and supporting code to make it work? There was a problem hiding this comment. Should we qualify average machine, also for posterity's sake? How about the current MacBook Air that retails for USD1099 according to Wikipedia? I'm also fine with say Thinkpad T420. There was a problem hiding this comment. And full documentation == nixpkgs? There was a problem hiding this comment. I would suggest that "cheapest widely available refurbished business laptop at the time" would be a good way to define "average machine". These things are ubiquitous (also due to their affordability, ~200 EUR is typical), are often representative of computing hardware from a generation or 2-3 ago in general, seem to have remained a reliable metric for this over the past 10 years, and in my experience the available offerings are quite consistent across countries, too. |
||
| - Closure-size of toolchain should be [small](https://github.com/NixOS/nixpkgs/issues/63513). | ||
| - Supports syntax highlighting (with Nix support) | ||
| - Active community supporting the tooling infrastructure | ||
| - Good conversion story from Docbook | ||
| - Can be used and integrated from NixOS option declarations | ||
|
|
||
| ### Nice-to-have's | ||
|
|
||
| - Annotations/links inside code listings for e.g. linking to option docs in `configuration.nix` snippets | ||
|
There was a problem hiding this comment. How is this different from Inter-file references for being able to link to options from anywhere? There was a problem hiding this comment. Shooting from the hip... I think it describes the same behavior from a reader's perspective, but it means the engine is doing more than identifying a code block, a syntax type, and handing it off to the appropriate highlighter. You have to parse (or at least partially parse) code blocks at build time, identify the different entities they contain, and use heuristics or direct lookups to resolve those local code entities into absolute paths to the appropriate documentation. If the highlighter isn't collaborating in this work, it probably also entails postparsing the highlighted blocks to inject the links, and potentially modifying the stylesheets to make sure the links don't stomp all over the syntax highlighting. There was a problem hiding this comment. Sounds complicated :) Are there examples of documentation format parsers doing this? |
||
| - Ability to make `$ `, `nix-repl>` and other prompts in command line snippets non-copyable | ||
| - Good search integration, e.g. by providing a well-functioning search field | ||
|
There was a problem hiding this comment. Is this about the output format having a search field? |
||
|
|
||
| ## Format Candidates | ||
|
|
||
| All format candidates are listed here with links to demonstrations showing off required features and to get a feel for it. Any tooling can be used to achieve this. | ||
| Ideally this should consist of a standalone repository created for this purpose, not a nixpkgs fork. | ||
|
|
||
| | Format | Source | Rendered | | ||
| | --- | --- | --- | | ||
| | Markdown | TODO | TODO | | ||
| | reST | TODO | TODO | | ||
| | Asciidoc | TODO | TODO | | ||
| | DocBook | TODO | TODO | | ||
| | Texinfo | TODO | TODO | | ||
| | Nix EDSL | TODO | TODO | | ||
|
|
||
| ### Closure sizes of different tools | ||
|
|
||
| TODO: Remove this section, as long as tools aren't too big, this isn't relevant or could be showed off in the demos | ||
| For the following comparison NixOS 19.09 is used. | ||
|
|
||
| | Name | Attribute | Closure size | | ||
| |--------------|-----------------------|--------------| | ||
| | Sphinx | `python3.pkgs.sphinx` | 195 MB | | ||
| | Pandoc | `pandoc` | 2.4 GB | | ||
| | Asciidoctor | `asciidoctor` | 1.0 GB (on master: 80% smaller) | | ||
|
There was a problem hiding this comment. So if we used 20.03, Asciidoctor's closure would be 80% smaller? There was a problem hiding this comment. Just for some concrete numbers, I ran whereas |
||
|
|
||
| ## Format Overviews | ||
|
|
||
| This section is to be used in the Discourse post, ordered before the poll. For each format it should contain: (in this order) | ||
| - A short description (history, where it's used, design goals, selling points) | ||
| - A short example of source code for it and links to the demonstrations from above | ||
| - Noteworthy advantages/disadvantages | ||
| - Links to tutorials, documentation and tooling | ||
|
|
||
| ### Markdown (CommonMark) | ||
|
|
||
| Markdown is probably the most well-known markup language, used for discussions on many websites such as GitHub, StackExchange, Reddit, Bitbucket and more. While the original description of Markdown was ambiguous, in current times [CommonMark](https://commonmark.org/) provides a clear specification for it. Markdown is designed to be easy to read and write. If you don't know it already, just after a [one minute tutorial](https://commonmark.org/help/) you can be productive with it. | ||
|
|
||
| Links: | ||
| - [The latest CommonMark specification](https://spec.commonmark.org/current/) | ||
| - [Pandoc](https://pandoc.org/) can convert from/to Markdown to/from many other formats | ||
| - [Sphinx](https://www.sphinx-doc.org/), a popular documentation generator, known for its [readthedocs](https://readthedocs.org/) pages supports Markdown | ||
|
|
||
| #### Why CommonMark instead of another Markdown flavor? | ||
| - CommonMark is very near to having a 1.0 release for a standardized and unambiguous syntax specification for Markdown | ||
| - The popular Sphinx documentation generator [supports CommonMark](https://www.sphinx-doc.org/en/master/usage/markdown.html) (in addition to reStructuredText) | ||
| - GitHub's Markdown is [a strict superset of CommonMark](https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/) and they are committed to having full CommonMark conformance | ||
|
|
||
| ### reStructuredText | ||
|
|
||
| [reStructuredText (reST)](https://en.wikipedia.org/wiki/ReStructuredText) is a file | ||
| format originally developed as part of the Docutils project for documenting the Python language. | ||
| Since then, support was added for reST to Sphinx, a popular tool for documenting (Python) projects, and pandoc. | ||
|
|
||
| With Sphinx it is possible to document various languages using the concept of [domains](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html). E.g., if we were to have a format for documenting Nix functions, we could implement a domain in Sphinx, as well as a parser that could parse Nix functions from comments and convert them to the Sphinx domain, as is done currently with the [Nixpkgs library](https://github.com/NixOS/nixpkgs/pull/53055). | ||
|
|
||
| Language: | ||
| - [Specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html) | ||
| - [Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) | ||
| - [Demo](https://docutils.readthedocs.io/en/sphinx-docs/user/rst/demo.html) | ||
|
|
||
| Tooling: | ||
| - [Sphinx](https://www.sphinx-doc.org/) | ||
| - [Docutils](https://docutils.sourceforge.io/) | ||
| - [Pandoc](https://pandoc.org/) can convert from/to reST to/from many other formats | ||
|
|
||
| Examples of users: | ||
| - Python | ||
| - Linux kernel | ||
| - CMake | ||
| - LLVM | ||
| - Majority of Python packages | ||
| - PowerDNS: ReST with [Sphinx](https://www.sphinx-doc.org/) for | ||
| manuals, guides and manpages | ||
|
|
||
| ### Asciidoc | ||
|
|
||
| TODO: Short overview | ||
|
|
||
| [Demo](https://github.com/opendevise/asciidoc-samples/blob/master/demo.adoc) | ||
|
|
||
| Tooling: | ||
| - [Antora](https://antora.org/) | ||
| - [Asciidoctor](https://asciidoctor.org/) | ||
|
|
||
| ### Texinfo | ||
|
|
||
| TODO: Short overview | ||
|
|
||
| Powerful, interactive and very nice to use (check out `pinfo`), but harder to write. | ||
|
There was a problem hiding this comment. Can we qualify what use means here (if not write)? Is it about the CLI experience? |
||
|
|
||
| ### Nix EDSL | ||
|
|
||
| With a Nix EDSL, linking to options can become trivial and very natural. Users won't have to learn another language either. Docs could also be written directly next to the thing they document with some convenience functions for annotating values with docs. | ||
|
|
||
| ### Docbook | ||
|
|
||
| TODO: Short overview | ||
|
|
||
| [Primer](https://docbook.rocks/) | ||
|
|
||
| ### Overall Comparisons | ||
|
|
||
| | Format | Rendered in GitHub | Adoption | Standardized | Goal | | ||
| | --- | --- | --- | --- | --- | | ||
| | Markdown | Yes | Great among websites | No | Easy to use | | ||
|
There was a problem hiding this comment. Is it not standardized if one follows CommonMark? See #64 (comment) There was a problem hiding this comment. If people have to ask "which markdown standard" it's not standardized imo. This is only a disadvantage if the other formats under discussion don't have that issue of course. There was a problem hiding this comment. Right, so we could say that Markdown itself is standardized, but the standard is insufficient for our goals (i.e. it doesn't have cross-references). |
||
| | reStructuredText | Yes | Great among tech docs | Yes | Easy to use, customizable | | ||
| | Asciidoc | Yes | ? | Yes | Easy to use, customizable | | ||
| | Docbook | No | ? | Yes | Semantic structure | | ||
|
|
||
| Cheatsheet comparison: http://hyperpolyglot.org/lightweight-markup | ||
|
|
||
|
|
||
|
|
||
| ## Some links that don't fit anywhere else in the RFC | ||
|
|
||
| TODO: Move or remove this section | ||
| - Linux kernel, why Sphinx/reStructuredText (2016): https://lwn.net/Articles/692704/ | ||
| - Why not Markdown: https://mister-gold.pro/posts/en/asciidoc-vs-markdown/ | ||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks | ||
|
|
||
|
|
||
| # Alternatives | ||
| [alternatives]: #alternatives | ||
|
|
||
| Not doing anything | ||
|
|
||
| # Unresolved questions | ||
| [unresolved]: #unresolved-questions | ||
|
|
||
| # Future work | ||
| [future]: #future-work | ||
|
|
||
| - This RFC only determines the doc format, implementing this change needs to be done in the future | ||
| - During that process it would be ideal to move the docs closer to the code they document | ||
| - Also during that it would be good to revise the docs overall and update them where necessary | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think poll is too vague, people should discuss on this RFC exactly what they'd like and then the shepherd team makes a decision.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's important to involve as many people from the community as possible, because they will be the ones writing and reading the docs. Unfortunately RFC's are known to be bad places for involving many people, since they tend to get long quickly and less-active people get overshadowed by very vocal people.
As you suggested to me though, having the poll happen before the RFC is accepted and using it as an input for the shepherd team might be a good idea.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I changed the RFC to reflect this