On Wed, 2022-08-24 at 15:08 +0200, Fabian Arrotin wrote:
Let's start a thread/discussion !
+1 on decommissioning the wiki in sake of a "git + static web" model. The model behind https://docs.fedoraproject.org/ looks pretty neat to me.
+1 on consolidating tools we are already using (e.g., jekyll). This would allow us in the Artwork SIG to work one a single theme (e.g., the same used for www) that can be applied to all documentation sites, consistently. It doesn't have to be a huge all-in-one documentation site (which may slow down the rendering process whenever new changes enter the repo). Instead, we may consider individual sites for each specific purpose we want to have documentation for (per SIG or SIG- specific repo maybe).
About the attachments, they could be stored in the same repo where the related documentation is stored in. Then, we could activate git LFS for them.
Using GitLab to store documentation repos may be useful to reduce infra maintenance and also take advantage of runners already in place.
About using Asciidoc, I don't know if we need to make use of all the documentation features it provides (e.g., includes for reusing content, etc.). It seems like there is a strong preference to use Markdown for the simplicity it provides. However, if we want great documentation features, then Asciidoc has my absolute vote. It has documentation features that Markdown doesn't have or even expect to have.