Fedora Infra Docs Hackfest

Basic info

Creating a new repo

Detailed description here: https://docs.fedoraproject.org/en-US/fedora-docs/contributing/adding-new-docs/. TL;DR:

  • Create a new pagure repo.
  • Grab the template, copy it somewhere.
  • Get rid of .git/ in the template, init a new local repo, and add your Pagure remote.
  • Change relevant stuff in site.yml and antora.yml and optionally rename the default module directory in modules/.
  • Push to the remote so everyone else can clone.

Repository structure

Covered in the README here: https://pagure.io/fedora-docs/template. Basically:

  • Each repo has a collection of modules in the modules/module_name/pages directory. Each file in this directory will be built as a separate HTML page in the output, which means don’t put parts (e.g. text boxes that you want to share across multiple pages) here. Each file in this directory must start with a top level heading (= Heading).
    The module_name can be anything you want; the default is ROOT which is just fine if you only have one module in a repository (which is somewhat recommended).
  • If you want to have a snippet of asciidoc in a separate file and share it in multiple files, make a partials/ directory on the same level as pages, put it there, and then include it using include::partial$filename.adoc[].
  • You can also create an examples/ directory in the same location. This is mostly useful in docs that contain examples generated by external scripts when the output isn’t valid asciidoc - you just output your snippets into that directory. If you want to use this, include files from there with include::example$filename[].
  • If you want to use images, put them into modules/module_name/assets/images, and include them in your files using image::filename[description]. Only use the filename, no path. The description is optional, you can just use [].
  • There’s no hierarchy, everything in pages/ is equal, which means Antora can’t autogenerate a table of contents - it doesn’t know or care where each page belongs. This means you have to manually reference each page in nav.adoc. If you don’t do this, your page will still be available if you know the URL (filename), but it won’t be easily findable. This also means you shouldn’t just put unfinished stuff in that directory thinking noone will see it, because search engines will still find it.
    The nav file is basically just another ASCIIDoc document, so it uses standard syntax. By default it’s a simple unordered list of xrefs (those are explained in Writing Tips below); you can also add sub-items which will create a list with collapsible parts, as you can see in the Quick Docs (source).
  • If you have multiple modules, each has its own navfile, and they must all be listed in antora.yml.

There is additional information in Antora docs, however you shouldn’t really need to go into too much detail. https://docs.antora.org/antora/2.3/

Building a local preview

Needs podman (preferred) or docker.
In the repo root, run ./build.sh && ./preview.sh, then open http://localhost:8080/ in your browser.

Publishing your stuff on the docs portal

You don’t really need to worry about this part, just ping pbokoc when you have something that’s at least somewhat ready to publish, and I’ll add it to the sitewide config. Afterwards, any changes that are merged into master (or some other branch that I can configure - just let me know which one(s) will be automatically published.

Note that currently, the site is rebuilt every full hour (3 PM, 4 PM, …), not upon a change, so you will need to wait to see your changes online. Note that the rebuild and republishing takes about 20 minutes. Every page has a footer that shows the time and date of the build you’re currently seeing; if it’s more than an hour old, the latest build hasn’t finished yet.

Writing tips

  • Know your audience. Infra docs are for at least somewhat technical people, however they might be new to this, so try to avoid jargon.
  • Consider that not everyone reading your docs is a native English speaker; keep your writing relatively simple (it doesn’t need to be Simple English on Wikipedia style, but avoid slang, break up your sentences, and avoid passive voice because it tends to confuse people).
  • Make sure to run a local preview and really check everything on every file you touched before you open a pull request. Antora is very light on validation, and things can break without any notice.
  • It’s recommended to put every sentence within a paragraph on a new line. It makes it much easier to review PRs on Pagure. Just hit Enter after every sentence, don’t put in newlines.
  • Lists are good because they help present information in separate chunks that are easier to understand.
    You can have multiple paragraphs and other elements (images, tables, …) in a single list item (ordered or unordered); just link every block element inside the single list item with + instead of just newlines. For example:
. List item 1 paragraph 1
+
Paragraph 2
+
Image

. List item 2
  • Avoid tables if you can because tables in ASCIIDoc are just painful.
  • If the document (as in the single page - a single file in pages/) is long, consider adding a table of contents. Do this by adding a :toc: on the line below the top heading, followed by an empty line. Like this:
= Long document is long
:toc:

In this chapter, we’ll discuss blah blah
  • You can enable a couple extra features, notably the kbd:[] syntax for marking up keys and key combinations, by putting :experimental: at the top of the file.
  • It’s often useful to link to other pages within the same repository and module. Use an xref:[] to do that, in the following form: xref:filename.adoc#anchor[link text]. Filename and link text are mandatory (technically link text isn’t, but omitting it means the text will be the filename and that’s ugly); the anchor is useful if you’re linking to a specific part of a file. Every subheading autogenerates its own anchor, so you can use that (find out by building a local preview and clicking the target heading), or you can add your own anchor by putting [[anchor_text]] at the target.
    You can also use an xref within the same file the same way; this is useful in longer files where you want to reference something discussed earlier.
    Additionally, you can use an xref to link to a page within another module. The syntax is the same, only the filename is prefixed with the module name:xref:another_module:filename.adoc#anchor[link text].
    The xref syntax can get much more complicated if you’re linking to a different repo on docs.fp.o; it’s possible, but rarely needed, so I won’t discuss that here. See Antora docs for details.
  • For external links, use link:https://example.com/[link text]. Just pasting a link into the sources works as well, but avoid that.
  • Admonitions are useful; they create an “infobox” within the text. Three types are commonly in use in Fedora docs: NOTE, IMPORTANT, and WARNING. You can see a few examples here. The syntax is:
[NOTE]
====
Note text
====

The difference between the three is generally that:
* Note is for useful extra information - “You might want to also know…”
* Important is for pointing out that what you’re telling the reader to do may result in a loss of data.
* Warning is when a step will result in loss of data (for example, in the install guide, we tell people to dd an image onto a USB drive, which wipes everything currently on it).

  • Mark up things like filenames, inline (in-paragraph) commands, package names, etc. with backticks - `command`, `filename`, etc.
  • For source examples, or for commands that aren’t inline, use:
[source,bash]
----
dnf install blah -y
----

The bash (or whatever language you’re using) is optional, but gives you syntax highlighting.

Select a repo