2026-09-28 09:40:25 <WhyNotHugo> o/
2026-09-28 09:40:34 <ikke> WhyNotHugo: welcome!
2026-09-28 09:51:46 <ncopa> hey! o/
2026-09-28 09:52:20 <ncopa> WhyNotHugo: at the conference we spoke a bit about what docs goes where. eg what goes to wiki and what goes to docs.a.o
2026-09-28 09:53:26 <ncopa> I have relatively recently learned about how to org your docs from divio: https://docs.divio.com/documentation-system/
2026-09-28 09:54:04 <ncopa> there is a talk on youtube there about the subject
2026-09-28 10:12:02 <achill> ncopa: this certainly makes sense i guess. but we should probably start with reference i guess?
2026-09-28 10:14:21 <ncopa> we should start with a plan on how we organize it. what goes where etc
2026-09-28 10:14:43 <ncopa> and then we should document how to contribute to docs
2026-09-28 10:14:58 <achill> yes
2026-09-28 10:15:02 <ncopa> which is a how-to I guess...
2026-09-28 10:15:44 <achill> i mean we can also start with a few people and then later try onboard new people when we have an initial docs
2026-09-28 10:16:00 <ncopa> i was wondering if we could do like all how-to's in wiki.a.o, but I just realized we need some how-tos in docs.a.o as well
2026-09-28 10:16:01 <ncopa> yeah
2026-09-28 10:16:32 <ncopa> I talked with WhyNotHugo about this at the conference
2026-09-28 10:17:08 <WhyNotHugo> I've been giving that some though and will write them down when I get a chance.
2026-09-28 10:17:56 <WhyNotHugo> Mainly, I think reference belongs in man pages, while how-to and some explanations in the wiki.
2026-09-28 10:18:08 <WhyNotHugo> Having HTMLified man pages which the wiki can link would be ideal.
2026-09-28 10:19:44 <WhyNotHugo> The "Installation" wiki page is very x86-centric; it needs to be split into the initial per-architecture pages for everything prior to setup-alpine.
2026-09-28 10:25:23 <pabloyoyoista> If I can interject a bit. The easiest way to move forward would likely be to start making it possible to contribute docs to docs.a.o
2026-09-28 10:25:41 <pabloyoyoista> There was https://gitlab.alpinelinux.org/alpine/docs/docs.a.o/-/work_items/5 where durrendal made some pretty good progress
2026-09-28 10:26:08 <pabloyoyoista> If that (https://krei.lambdacreate.com/Alpine/mkdocs.a.o) would be deployed and made official, then it would be a lot easier to contribute
2026-09-28 10:26:52 <pabloyoyoista> Trying to make the perfect plan is great, but if it hinders on moving forward, might be better to just have a simple plan that is easy to execute, and slowly build on top of it
2026-09-28 10:30:21 <ncopa> simple plan, small steps are good. yes. but we need to know what direction.
2026-09-28 10:43:53 <WhyNotHugo> agreed, a one markdown file -> one html page design is much easier to reason about too.
2026-09-28 10:45:05 <WhyNotHugo> mkdocs in particular is pretty bad at accessibility tho.
2026-09-28 10:56:30 <WhyNotHugo> Do we have any idea how we'd handle divergence across releases?
2026-09-28 11:20:12 <ikke> WhyNotHugo: Antora allows you to publish documentation per version
2026-09-28 11:20:40 <ikke> I think that would be mostly relevant for user documentation. Governance and developer documentation would not be tied to a release
2026-09-28 11:35:23 <durrendal> Regardless of what path forward we take, if I can help, please let me know. More than happy to write or help dogfood additional systems (or double down on Antora if that's the mood)
2026-09-28 11:37:09 <durrendal> I saw the comment about mdbooks WhyNotHugo, happy to convert what I have for mkdocs to mdbooks so it could be compared more easily
2026-09-28 11:48:31 <durrendal> I could also put the mkdocs demo back up alongside it. It was very easy, but the accessibility argument is a solid concern
2026-09-28 16:12:51 <WhyNotHugo> re version: I just meant: does docs/master track the current edge, and we tag docs when we tag aports?
2026-09-28 16:13:05 <WhyNotHugo> I think something this simple should suffice, especially as a start.
2026-09-28 16:26:36 <Sertonix[m]> Yes, I think it should be something that is maintainer together edge and only edge. It would be good if the tooling we choose is able to deal with multiple branches if we start to need it.
2026-09-28 16:29:02 <Sertonix[m]> Ideally there would be an aport with the doc for offline usage as well. But it would require some effort to make them usable without a browser.