# Fedora Infra Docs Hackfest

## Basic info

* Fedora Docs are published on https://docs.fedoraproject.org/en-US/docs/
* Sources are stored in a variety of repositories, mostly on pagure. The easiest way to find where a specific document repo is is to open the document on the docs site and click “Edit this Page” in the top right corner.
* The sources are all ASCIIDoc. Markup quick reference: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
* If you’re lost, ping pbokoc (#fedora-docs on FreeNode)

## 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](https://pagure.io/fedora-docs/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.