On 9/24/19 11:06 PM, Randy Barlow wrote:
On Tue, 2019-09-24 at 16:55 -0400, Randy Barlow wrote:
On Tue, 2019-09-24 at 15:20 +0200, Petr Bokoc wrote:
Sure! You guys are the experts and you know all about what people
need to do and how to do it, so it's best if you do most of the
actual content writing; I'm happy to help you with markup,
structure
and that sort of stuff. Some basic info about how the docs site
works
is in the template repo README: 
https://pagure.io/fedora-docs/template

Once we have something publishable I'll add it to the site and link
it from https://docs.fedoraproject.org/en-US/engineering/
Great!

Do you have a suggestion for a particular git repository to be used
for
this, or should we start a new git repository just for these docs?
Or do you recommend using the repo that pingou suggested: 
https://pagure.io/infra-docs-fpo
Pingou's repo is OK to use. I created a new module for these docs within it; the table of contents of this module will appear below the main module's navigation. We can easily change that later if we need to.
Any sources go into the module's pages/ directory, and don't forget to link them (xref:filename[link text]) in the module's nav.adoc, otherwise they'll be built and available if you have the page URL, but won't be linked in the sidebar.
If you want to use any images, put them in assets/images/ and use "image::only-the-filename-without-directories[optional alt text]".
Each source file in pages/ needs to start with a level 1 heading ("= Heading", like index.adoc does), otherwise Antora will still build it but all sorts of weird stuff will start happen.
If you want to reuse a snippet of text (like, say, have some kind of a warning box in multiple places but stored only in a single source so you can easily edit it once and see the change everywhere), make a modules/communishift/partials/ directory and put .adoc files containing only these reusable snippets in them (no heading on top or anything), and include them in other sources with "include::partial$filename.adoc[]". These partials won't be built as separate pages, Antora ignores them unless they're included somewhere else, so you won't end up with people coming in from google and finding only the snippet.
Generally don't worry about markup too much, once you're at least somewhat done I'll go through everything.
Cheers,
Petr