This is more of a question than an issue. Once it is affirmatively answered, the issue can be closed.
I am trying to decide where it makes the most sense to host quick, technical documentation for a specific set of tools and scripts related to Fedora.
In CommOps, we want to "pretty up" our toolbox repository, which will hold various scripts or individual tools for querying fedmsg data. I'd like to write some documentation to go along with it. I was also considering a documented page for Fedora contributors with an IRC cheat-sheet, sort of like this gist.
I like hosting docs in git repos on Pagure. I like the format of delivery via the Fedora documentation site. However, I don't feel these docs shouldn't crowd the main index and pages of the documentation site, or at least, not in a way that decreases visibility on more useful resources about our team, like the CommOps and Community Blog pages.
In this situation, what does the Fedora Docs team recommend I do? Should we pursue an AsciiDoc + Antora solution or would it make more sense to use the native Pagure documentation tools, like for ReadTheDocs integration? Has the Fedora Docs team given any thought to situations like this yet?
It's a ways off before we would have any documentation to publish, but I wanted to ask early and get a clear idea of the least path of resistance before committing to expanding documentation for our toolbox.
Thoughts?
If those docs are related to a specific team/working group/SIG, I think these could live within the team/working group/SIG's pages.
Technical teams: https://docs.stg.fedoraproject.org/en_GB/fesco/latest/teams/
Mindshare teams: https://docs.stg.fedoraproject.org/en_GB/mindshare/latest/teams/
What do others think?
@asamalik My original concern about grouping them with the team / SIG pages was this:
However, I don't feel these docs shouldn't crowd the main index and pages of the documentation site, or at least, not in a way that decreases visibility on more useful resources about our team, like the CommOps and Community Blog pages.
For example, if I wanted to document a simple script or a one-off useful thing like a meeting guide, I wouldn't want this to clutter my team's other, more important documentation. Unless there was a way to rank some pages higher about others or to have a recursive ToC in the sidebar, then I would be more open-minded to this way.
Does this make sense? If so, do you also see the same thing I mean or do you feel differently?
@jflory7 it does and I think I've got you covered!
You define the menu for your documentation space manually in a file. For example, the Modularity docs' menu is defined in this nav.adoc file.
Also, you can have a look at the Antora source template.
So you could create a foldable section in the menu with such guides. Would that work for you?
@asamalik Neat! This is exactly what I had in mind. A nested navigation would solve this concern for me. It would be cool to document this somewhere for when I have a chance to revisit how we are doing docs. Unfortunately, I am blocked by other sessions I am organizing for all the docs writing / Antora sessions at Flock, so I'm not sure I will have a chance to do it then (so having a place to reference how to do this later will definitely help!).
@jflory7 Hi, can I close this issue or do you need anything else?
@pbokoc I think it's okay to close now, thank you.
Metadata Update from @pbokoc: - Issue status updated to: Closed (was: Open)
Login to comment on this ticket.