[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,142 @@ | ||
| --- | ||
| 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: (names, to be nominated and accepted by RFC steering committee) | ||
| shepherd-leader: (name to be appointed by RFC steering committee) | ||
| related-issues: (will contain links to implementation PRs) | ||
| --- | ||
|
|
||
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| The Nix community wants to move away from using Docbook as our documentation format and replace it with something else. However it is unclear what it should be replaced with. This RFC gives a concrete process for determining the new documentation format. It does NOT say what format should be used. | ||
|
There was a problem hiding this comment. Should this only be about the format, or also the structure? There was a problem hiding this comment. I think changing the structure is another step and should be discussed independently. There was a problem hiding this comment. I think only the format for now. This RFC should be seen as an official decision that format X will be the one to use, and that people are free to work towards that without having to worry about wasting efforts due to it being rejected. There was a problem hiding this comment. Isn't suitability of format closely linked to the desired structure?
infinisil marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| # Motivation | ||
| [motivation]: #motivation | ||
|
|
||
| There's been enough bike-shedding over the documentation format to use. We should finally settle this debate by deciding and committing on a single format such that we can move forward and improve our documentation situation. | ||
|
|
||
| # 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. | ||
| - A short objective overview of each valid candidate format is written, along with their advantages/disadvantages | ||
| - The RFC is accepted | ||
| - 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 | ||
| - Whatever format wins in the poll is chosen as the new default documentation format. If later it is discovered that the winner is infeasible for any reason, e.g. if it doesn't meet the requirements after all, the format on second place is chosen instead, and so on. | ||
|
|
||
| ## Poll | ||
|
There was a problem hiding this comment. 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. 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. I changed the RFC to reflect this 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:
|
||
|
|
||
| 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 | ||
| - Inter-file references for being able to link to options from anywhere | ||
domenkozar marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Ability to create link anchors to most places such that we can link to e.g. paragraphs | ||
| - Errors are easily and quickly detectable, e.g. with a fast and good processor, a live-view, or highlighting editor plugins | ||
| - 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. |
||
|
|
||
| ### 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 `$ `'s in command line snippets non-copyable | ||
infinisil marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Format overviews | ||
|
|
||
| Should contain for each format: | ||
| - A short description | ||
| - Noteworthy advantages/disadvantages | ||
| - Links to tutorials, documentation and tooling | ||
| - A short sample | ||
|
|
||
| ### 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 | ||
|
|
||
| TODO: Short overview | ||
|
|
||
| [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/) | ||
|
|
||
| ### 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/) | ||
|
|
||
| ### 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 | ||
|
|
||
| - Linux kernel, why Sphinx/reStructuredText (2016): https://lwn.net/Articles/692704/ | ||
|
|
||
| TODO: More online comparisons? | ||
|
|
||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks | ||
|
|
||
|
|
||
| # Alternatives | ||
| [alternatives]: #alternatives | ||
|
|
||
|
|
||
| # Unresolved questions | ||
| [unresolved]: #unresolved-questions | ||
|
|
||
|
|
||
| # Future work | ||
| [future]: #future-work | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.