@cybaright at a high level, the way this works is that you create a git repo (on Pagure, GitLab, etc) to store your documentation. When you're ready, we can add that repo to the configuration for the docs site.

The Docs Template repo has a starting point for you, with some instructions on customization. You may also want to look at the Docs Contributing docs.

I strongly suggest as you develop the docs that you split them into user-facing and SIG-facing. You can do that by having multiple "modules" in the repo or by using two repos. (For simplicty, I suggest multiple modules, but it's up to you). You can see the work I'm doing to split the IoT docs as an example.

As you are working on your repo, I'd be happy to take a look and offer help. I'm sure anyone else on the Docs team would as well.

Thank you. I have a few questions please, bit long sorry so please read when you have time : )

• Pagure vs Gitlab. Any decisive reason to prefer one over the other (presumably can use remote pull requests and use both later if ever needed?). My idea is that either would be fine and since members possibly prefer Pagure, that I choose that?

• Creating Pagure repo. I've found that Mobility already has a Pagure project here https://pagure.io/fedora-mobility , would this be the best place to put the new doc repo files rather than my own personal user space or another new project space? Specifically, I could create a docs folder with two subfolders (user-docs & sig-docs) as per your advice on splitting above. Alternatively, I could create an entirely new project (presume pagure project terminology means repo?)? My idea would be to host the docs within the existing mobility pagure file space as that seems more logical to me and my guess is that a docs folder should be sufficiently separate from any other non doc files which might arise in that file space? Which approach seems better to you?

• Fedora Docs Policy? Mobility SIG has a wiki here https://fedoraproject.org/wiki/Mobility , is Fedora's docs policy to try to replace wiki's generally and move wiki content to the docs tree or is there generally a role for both wikis and docs? My gut feel is that maintaining both may be needless duplication for mobility sig?, in which case my process here would be more of a migration of the wiki to docs? Is there an existing Wiki to Antora conversion process?

• Initial content on docs - would your advice be to initially duplicate/replace the wiki content over on docs and then develop/diverge from there or would it be simpler to start with fresh content on docs. My idea was to duplicate the wiki into docs as the starting point for the user-facing module and also create a new SIG-facing module as per your info above and after the docs is up and running remove the old wiki. Sound ok?

Appreciate the advice many thanks : )

• Pagure vs Gitlab.

This is entirely up to the SIG. Most teams use Pagure, but some use GitHub or GitLab. With the Fedora namespace in GitLab available now, the Docs team has started the process of moving our repos there because we want some of the cross-repo features it has. On the other hand, the docs I maintain for program management are on Pagure and will likely remain there.

• Creating Pagure repo. I've found that Mobility already has a Pagure project here https://pagure.io/fedora-mobility , would this be the best place to put the new doc repo files rather than my own personal user space or another new project space? Alternatively, I could create an entirely new project (presume pagure project terminology means repo?)? My idea would be to host the docs within the existing mobility pagure file space as that seems more logical to me and my guess is that a docs folder should be sufficiently separate from any other non doc files which might arise in that file space? Which approach seems better to you?

I'd definitely use a "shared" space so that the docs carry on after you leave the project (which everyone does eventually). If you expect to have a many unrelated repos eventually, it might be good to have a fedora-mobility namespace and a docs repo under that (so fedora-mobility/docs). But that's also something you can change later if needed. For now, I'd start with the basically-empty existing repo unless you already have plans for more stuff to go in there.

• Fedora Docs Policy? Mobility SIG has a wiki here https://fedoraproject.org/wiki/Mobility , is Fedora's docs policy to try to replace wiki's generally and move wiki content to the docs tree or is there generally a role for both wikis and docs? My gut feel is that maintaining both may be needless duplication for mobility sig?, in which case my process here would be more of a migration of the wiki to docs? Is there an existing Wiki to Antora conversion process?

The Fedora Council's position is that the Docs site should be used for "permanent" content and the wiki is for shared working space. That's not universally true, but that's a good thing to work toward. So I'd suggest copying wiki content into docs. Once your site is live, we can set up an automatic redirect on wiki pages.

You can use Pandoc to convert MediaWiki markup to Asciidoc. However, my personal preference is to manually update the syntax when I move a page. This causes me to pay more attention to the content, too, and helps catch things that are poorly-worded or wrong.

• Initial content on docs - would your advice be to initially duplicate/replace the wiki content over on docs and then develop/diverge from there or would it be simpler to start with fresh content on docs. My idea was to duplicate the wiki into docs as the starting point for the user-facing module and also create a new SIG-facing module as per your info above and after the docs is up and running remove the old wiki. Sound ok?

That's what I would suggest. :-)

Thank you Ben, brilliant info.

Ben, just a quick update on this also. If I read the mood of the longer term members of the Mobility SIG correctly (from Matrix), whilst there was some quite strong initial interest expressed in setting up this docs space, I haven't found much subsequent enthusiasm and I'm wary of taking on this task solo in the absence of broader interest. If the SIG wants to push this again later, then I remain happy to run with it, for now though it's on hold. Apologies for the false start but really appreciate your input and no doubt this issue will gain momentum again in the near future ; ) thanks

Thanks for the update. I understand not wanting to take sole ownership. I'll go ahead and close this issue for now and you can re-open or open a new one when you're ready.