2025-08-01 10:23:41 <prabu> invoked, thanks. knowledgeable editors is a main prerequisite for accurate wiki content. we currently lack editors with knowledge..currently developers are already having their hands full. so we can only hope to get new users with knowledge and a flair for editing..
2025-08-01 10:25:29 <prabu> achill, i'll appreciate if you can shed more light on "almost everything needs rework" and "do not have a lot of quality"
2025-08-01 10:27:21 <sertonix[m]> Last time I looked into the wiki I felt like we should focus on linking to external/upstream documentation for general stuff and only cover the alpine specific stuff in detail. That way it could be a lot easier to maintain.
2025-08-01 10:27:38 <prabu> out-of-date is a different issue say compared to ambiguous writing/wrong instructions/missing steps etc..
2025-08-01 10:30:32 <prabu> sertonix, true.. i think the initial focus should be to detail as much as possible "alpine specific stuff"
2025-08-01 10:37:07 <prabu> there were a lot of missing pages/ or information located within other pages.. in the recent past these information/pages have been moved around to make things easier for both editors/users..
2025-08-01 10:42:17 <prabu> at least from desktop perspective, i think wiki is usable now... any actionable idea to identify poor quality stuff is welcome
2025-08-01 10:45:02 <prabu> not translating because of quality issue, i'm unsure if this is good idea. 
2025-08-01 10:46:07 <prabu> generally translations are not done 100% verbatim..the translator decides what's important and focuses only on that..
2025-08-01 10:46:39 <prabu> so we should welcome translations/translators, and faclitate it with suitable changes in wiki, if needed..
2025-08-04 02:50:01 <vhns> As per https://wiki.alpinelinux.org/wiki/Nftables it says that there should be packaged rules for nftables, and that they are being implemented/subject to change. Is this still the case? I ask because they don't seem available on the stable nor edge repositories. If not, can I remove that section from the wiki?
2025-08-04 04:19:06 <prabu> i can see some packaged nftables rules here https://tpaste.us/1yD4
2025-08-04 04:19:49 <prabu> for waydroid, kdeconnect etc..
2025-08-04 04:29:22 <prabu> but the specific example and locations needs to be fixed https://tpaste.us/pymm
2025-08-04 04:33:25 <vhns> hmm
2025-08-04 04:52:22 <prabu> please feel free to fix wiki, as quite a number of pages needs updating
2025-08-06 10:45:51 <pabloyoyoista> ikke clandmeter would you have time to have some look at https://gitlab.alpinelinux.org/alpine/docs/governance/-/merge_requests/2 and https://gitlab.alpinelinux.org/alpine/infra/alpine-mksite/-/merge_requests/107
2025-08-06 10:45:57 <pabloyoyoista> before ncopa is back from holidays?
2025-08-06 10:46:12 <pabloyoyoista> Hope none of those are too controversial
2025-08-06 10:46:35 <pabloyoyoista> Merging https://gitlab.alpinelinux.org/alpine/docs/docs.a.o/-/merge_requests/1 wouldn't hurt either
2025-08-07 04:11:19 <ncopa> hey! im back now. but with jetlag, and probably a fever
2025-08-07 04:13:10 <ncopa> yeah i have fever :-/
2025-08-07 05:53:19 <ikke> ncopa: welcome back, sorry to hear you have a fever
2025-08-07 10:18:36 <pabloyoyoista> really sorry :( Hope you manage to rest and recover
2025-08-13 10:56:26 <pabloyoyoista> ikke clandmeter ncopa: friendly ping about the MRs above?
2025-08-14 19:57:59 <ikke> https://lwn.net/SubscriberLink/1032604/73596e0c3ed1945a/
2025-08-14 19:58:28 <ikke> pabloyoyoista: I'm concentrating on migrating the mirror infra atm, will look at it when that's done
2025-08-14 20:41:53 <pabloyoyoista> Thanks a lot for the follow-up!
2025-08-15 03:29:48 <prabu> @ikke, thanks for sharing the lwn article on archwiki
2025-08-15 06:10:39 <prabu> i've added a template Template:Accuracy based on Archwiki template and it's used in Bridge page of wiki.a.o. please see if further changes are required in the template.
2025-08-15 09:20:48 <prabu> Template:Verified has also been created. It's used in seatd page of wiki.a.o. With the above two extensions, we can help track both success and failure of wiki pages..
2025-08-15 09:27:10 <prabu> if the team finds it useful, consider adding a Sitenotice requesting users to mark pages using templates like verified, Accuracy,Obsolete etc..
2025-08-15 09:43:24 <ikke> prabu: But can't that become autdated?
2025-08-15 09:49:06 <prabu> true, currently users do not even know whether something works as only edits are in history. this verified allows tracking of relevency of page
2025-08-15 09:49:31 <ikke> Yes, but it's a snapshot
2025-08-15 09:49:36 <ikke> something we have to additionally maintain
2025-08-15 09:49:58 <ikke> Saying a page is verified has no additional value if that info has become outdated
2025-08-15 09:50:30 <prabu> there's no additional maintenance. it allows wiki users to tell others "he used it and found working"
2025-08-15 09:50:32 <ikke> Does it include extra data like when it was verified or perhaps against what alpine version?
2025-08-15 09:51:44 <prabu> template can be modified to capture other information, but i want something simple begin with. the edit summary is a good place to add version information..
2025-08-15 09:53:18 <prabu> this involves adding one word {{Verified}} and if it already exists, just increment one number {{Verified|1}}
2025-08-15 09:53:32 <prabu> to the top of any wiki page..
2025-08-15 09:54:34 <ikke> say 10 users verified it 10 years ago, has that more importance than 1 user having verified it last week?
2025-08-15 09:58:45 <prabu> recency has more value and numbers are there just to make a non-intrusive change. history of verified markings will clearly tell users to be careful or increase their confidence in using a page
2025-08-15 09:58:51 <prabu> currently we don't have anything to guide ourselves and our users. this provides a simple mechanism to let users themselves to help improve the wiki by marking..
2025-08-15 10:00:01 <prabu> this also allows us to see which pages are actively used and of course everthing depends on users chosing to use the template
2025-08-15 10:00:20 <ikke> It does not give an accurate picture
2025-08-15 10:02:42 <ikke> Having an indication on when it was verified (without having going through the history of a page) at least gives information to the user how relevant it still is
2025-08-15 10:03:09 <ikke> At some point you end up in the same situation when many pages have a verified tag, but turn out to be outdated
2025-08-15 10:03:50 <ikke> s/when/where
2025-08-15 10:05:36 <prabu> accuracy can never be achieved in a technical wiki with so many changes..what this can do is to allow users to mark pages, so it becomes helpful. showing a date next to verified doesn't help much in improving the accuracy
2025-08-15 10:05:45 <prabu> https://wiki.alpinelinux.org/w/index.php?title=Template:Verified&oldid=30713
2025-08-15 10:06:12 <prabu> i removed that because, it requires more hassle without bringing a lot of benefit..
2025-08-15 10:09:36 <prabu> this template is the most non-intrusive to tell users that someone other than the page editor has successfully followed the instructions and with one click allows to see the history too..
2025-08-15 10:10:11 <ikke> In my opinion, these verifications decay over time. Without incorporating that, the value of it diminishes over time as well
2025-08-15 10:12:21 <ikke> And voting mechanisms usually turn out to be just popularity contests
2025-08-15 10:16:19 <prabu> i understand your thoughts. thanks @ikke
2025-08-15 10:18:16 <ikke> We also need to take into account that someone may have verified the page, then someone makes significant edits
2025-08-15 10:18:23 <ikke> The verification is no longer valid
2025-08-15 10:18:52 <ikke> (or even subtle edits that may have significant impact)
2025-08-15 10:21:38 <prabu> true.. in case of major edits, we have to adjust our [[Help|Editing]] document to remove the {{Verified}} template from the page. Also the history will show to the users the changes that happened since the last verification..
2025-08-15 10:23:19 <prabu> s/to remove /instruct editors to remove
2025-08-15 10:26:14 <ikke> yes, but someone would need to verrify -> extra maintenance
2025-08-16 07:32:08 <prabu> @ikke, as a trial, i've added a box on this page https://wiki.alpinelinux.org/wiki/Daily_driver_guide
2025-08-18 20:19:58 <pabloyoyoista> Does anybody know where does the theme of the docs come from?
2025-08-18 20:20:00 <pabloyoyoista> https://gitlab.alpinelinux.org/alpine/docs/docs.a.o/-/blob/master/site.yml?ref_type=heads#L16
2025-08-18 20:36:32 <ikke> I guess Chloe (SpaceToast) created it?
2025-08-18 20:37:55 <pabloyoyoista> And is it stored anywhere?
2025-08-18 20:38:55 <pabloyoyoista> Like, it seems it's some kind of redirect since http://docs.alpinelinux.org/theme-source/ui-bundle.zip returns 404
2025-08-18 20:39:24 <pabloyoyoista> Where is that site deployed? I could not find the compose or the source of that zip in the infra repo
2025-08-18 20:39:36 <ikke> https://docs.alpinelinux.org/theme-source/ui-bundle.zip gives a 200 for me
2025-08-18 20:39:56 <ikke> pabloyoyoista: It's hosted in an lxc container
2025-08-18 20:41:24 <pabloyoyoista> Ok, interesting. So then it was hand-crafted at some point and then uploaded to the site?
2025-08-20 08:53:11 <pabloyoyoista> ikke: I've now uploaded the source bundle to https://gitlab.alpinelinux.org/pabloyoyoista/ui-theme Could it be moved to the "docs" subgroup?
2025-08-20 08:53:36 <pabloyoyoista> Seems the sources might have gotten lost, which is a bit annoying
2025-08-20 08:53:46 <pabloyoyoista> But better than nothing
2025-08-20 09:05:09 <ikke> Was it perhaps derived from https://gitlab.com/antora/antora-ui-default? Or is that completely different?
2025-08-20 09:10:45 <ikke> pabloyoyoista: done
2025-08-20 09:11:55 <pabloyoyoista> ikke: thanks! And yes, it is derived from there. But I have no expertise in UI, and the changes don't look completely trivial to me, so no idea how to handle it
2025-08-20 09:22:05 <ikke> checked the docs container, but don't see any source there either
2025-08-20 09:23:43 <pabloyoyoista> Alright, I'm working on antora docs for pmOS right now. So maybe we can find somebody either in alpine or pmOS that has the skills
2025-08-20 09:33:39 <ikke> pabloyoyoista: We have also been looking at alternatives to antora
2025-08-20 09:34:37 <achill> there are a few good alternatives that work really fine with just md or rst
2025-08-20 09:34:41 <pabloyoyoista> ikke: Do you have thoughts about alternatives? Or reasons you'd like to move out of Antora?
2025-08-20 09:35:08 <ikke> pabloyoyoista: mostly because antora is not commonly known. Something like mkdocs or hugo
2025-08-20 09:35:50 <pabloyoyoista> Interesting. I did some few hours of research the other day, let me put what I found somewhere
2025-08-20 09:38:34 <achill> btw regarding the rewritten developer documentation i'm working on, im not sure where a good place is, just in aports/PACKAGING.md or something would be more discoverable than docs.a.o
2025-08-20 09:45:01 <pabloyoyoista> achill ikke: https://gitlab.postmarketos.org/-/snippets/14
2025-08-20 09:45:28 <pabloyoyoista> I guess that's the coll part of Antora. You can have a file in another repo, and can still make it show up in docs.a.o :)
2025-08-20 09:53:15 <pabloyoyoista> Anyway, would be good to know if a decision is made, since might be nicer to use the same in both places. Personally I didn't know Antora, but it was easy to get started and the featureset seem really nice
2025-08-20 09:54:24 <ikke> No final decission has been made, and generally our policy is that the people who do the work get a say in what we use
2025-08-20 10:04:21 <pabloyoyoista> 👍️
2025-08-20 10:07:00 <ikke> One thing that would be nice is that we tie the user handbook version to the alpine version
2025-08-20 10:19:16 <durrendal> Thanks for the invite ikke :) 
2025-08-20 10:25:30 <ikke> yw
2025-08-20 10:26:10 <ikke> pabloyoyoista: made this snippet weighing various options for rendering documentation: https://gitlab.postmarketos.org/-/snippets/14
2025-08-20 10:35:10 <durrendal> Hmm interesting antora seems like the favored choice reading through it. Didn't realize it had some sort of automatic translation capabilities.
2025-08-20 10:36:05 <durrendal> I'll also have to read that link about not using markdown, I think my knee jerk reaction is that markdown is simpler, ergo easier to contribute to, than asciidoc
2025-08-20 10:38:16 <pabloyoyoista> Seems like the automatic translation might be some effort to setup, I haven't had time to test it yet. But if it worked, would be great
2025-08-20 10:39:01 <pabloyoyoista> I guess the point in that blog post against markdown is: will we ever need to do anything more complex than the basics? If so, then it's the wrong tool
2025-08-20 10:39:31 <pabloyoyoista> And just looking at the current docs, it indeed seems like "vanilla markdown" is too simple
2025-08-20 10:40:34 <pabloyoyoista> I was also hesitant at the beginning to use something different, since I had never used adoc when I started looking into alpine governance docs last month. But it's been surprisingly easy
2025-08-20 10:49:34 <durrendal> Agreed on all points. We probably do want something more flexible than plain markdown.
2025-08-20 10:50:40 <durrendal> And honestly adoc is not that bad, I hadn't used it before reworking the user handbook, it obviously wasn't prohibitive. It was more confusing to figure out how to all pieced together since it's several repos, and I'm hoping the makefile I added and the CI I plan to add will remove that friction entirely 
2025-08-20 10:51:45 <durrendal> Happy to look into the automagic translation as well :)
2025-08-20 10:53:42 <durrendal> Fedora's use of antora makes ours look cute, probably worth digging into more deeply to see how antora scales
2025-08-20 10:57:43 <pabloyoyoista> Yeah, I think having had that would have helped me quite a lot first try
2025-08-20 11:00:33 <pabloyoyoista> The Fedora one is also certainly massive. But allows discovery very, very nicely. As opposed to e.g: GNOME's Sphinx websites setup: https://handbook.gnome.org/, https://welcome.gnome.org/, https://apps.gnome.org/, ....
2025-08-20 11:28:46 <achill> i have also heard of mkdocs.org or mostly its frontend readthedocs.com
2025-08-20 11:32:05 <achill> oh looks like this is sphinx
2025-08-20 11:35:53 <ikke> mkdocs is something I have suggested earlier as well
2025-08-20 11:35:57 <ikke> invoked has been looking into that
2025-08-20 11:42:41 <durrendal> GNOME's website honestly looks really nice, at least on mobile. Though it feels more geared towards user docs, fedora feels more like sysadmin documentation to me
2025-08-20 11:43:28 <durrendal> mkdocs is what Ansible uses I believe, I've always found that documentation to be very easy to approach & search.
2025-08-20 11:45:46 <durrendal> ikke: do you have any personal experience with anything other than antora? Part of the discussion likely needs to be what presents the least maintenance burden to the infra team to deploy and maintain
2025-08-20 11:46:07 <ikke> durrendal: No, I haven't
2025-08-20 11:47:14 <pabloyoyoista> The difference between GNOME and Fedora might as well be the skill of the design people involved xD
2025-08-20 11:47:42 <pabloyoyoista> Is there anybody else using mkdocs?
2025-08-20 11:48:04 <durrendal> ikke: same here, though it's all static site generation, so I suppose any CI/k8s work we do would be cross applicable
2025-08-20 11:56:37 <ikke> https://docs.renovatebot.com/
2025-08-20 12:11:10 <durrendal> https://github.com/renovatebot/renovatebot.github.io <- definitely mkdocs
2025-08-20 12:11:41 <durrendal> looks good too honestly, I find this more easy to navigate than what antora produces
2025-08-20 12:12:55 <durrendal> https://github.com/renovatebot/renovate/blob/main/docs/usage/about-us.md
2025-08-20 12:12:57 <durrendal> https://docs.renovatebot.com/about-us/
2025-08-20 12:13:11 <durrendal> for comparison, the site page, and the markdown it's rendered from
2025-08-20 12:18:18 <durrendal> https://github.com/pebble-dev/developer.rebble.io <- Pebble used Jekyll
2025-08-20 12:30:00 <pabloyoyoista> Those renovate docs are surely easy to navigate. The problem is again md 😅 And single place, if that was a concern
2025-08-20 12:31:30 <durrendal> I don't personally see any issues with using a monorepo for docs. It's one place to find all MRs, Issues, and configure CI to enforce style/do deployments
2025-08-20 12:31:51 <durrendal> a little less confusing for people to reason about if they're new to contributing too
2025-08-20 12:35:45 <achill> yeah i like monorepos :)
2025-08-20 12:37:56 <durrendal> pabloyoyoista: what special formatting in antora do you think we should be using, or we currently use that you think is valuable to preserve?
2025-08-20 13:11:41 <ncopa> k0s also use mkdocs https://docs.k0sproject.io/stable/
2025-08-20 13:18:42 <pabloyoyoista> durrendal: lists like https://gitlab.alpinelinux.org/alpine/docs/user-handbook/-/blob/master/modules/ROOT/pages/index.adoc?ref_type=heads&plain=1#L28 give more alternatives so that not every list looks the same and it's easier to parse visually
2025-08-20 13:18:59 <pabloyoyoista> But most of all the Warning and Tip tags: https://gitlab.alpinelinux.org/alpine/docs/user-handbook/-/blob/master/modules/Installing/pages/setup_alpine.adoc?ref_type=heads&plain=1#L22
2025-08-20 13:20:24 <pabloyoyoista> Regarding the monorepo, maybe that's not a concern in alpine. Downstream will be totally worth it I think
2025-08-20 13:21:41 <pabloyoyoista> Things like tittles for code blocks etc. might also be interesting
2025-08-20 13:21:54 <pabloyoyoista> But that might be less relevant
2025-08-20 13:22:17 <pabloyoyoista> We can still do monorepo with antora xD
2025-08-20 13:24:42 <durrendal> ah you're taking it from the angle of potentially adhering pmos (or other derivative projects) documentation onto the official alpine documentation then? ie: if pmos wanted to host their own alpine docs with pmos specific sections included on their own domain, antora would easily facilitate that
2025-08-20 13:26:15 <pabloyoyoista> I wasn't thinking about that. I was thinking about doing the same thing in both places. And we will have documentation in multiple repositories because we might end up placing docs about devices in 'our aports' (pmaports)
2025-08-20 13:26:30 <pabloyoyoista> But that's a great idea nonetheless :D
2025-08-20 13:26:55 <pabloyoyoista> s/I was thinking about doing the same thing in both places/I was thinking about doing the same thing in both places just for shake of consistency :D/
2025-08-20 13:28:48 <ncopa> looks like mkdocs has markdown extensions. https://python-markdown.github.io/extensions/
2025-08-20 13:29:30 <ncopa> so you have have Warnings and Tips (admonitions)
2025-08-20 13:29:55 <ncopa> also supports definition lists https://python-markdown.github.io/extensions/definition_lists/
2025-08-20 13:31:08 <pabloyoyoista> Right, that's exactly the criticism in the blog post :D Then it's not easy or portable anymore, you need to know about the syntax of an specific extension, that might be different to that of another extension
2025-08-20 13:32:01 <pabloyoyoista> But anyway, I've spoken enough. If you all like mkdocs, go for it :D
2025-08-20 13:36:22 <durrendal> from an infra perspective, we already have mkdocs packaged. So it would be easier to work with from that angle. I'm not a fan of my "shove npm installed antora into a container" solution I came up with.
2025-08-20 13:37:32 <durrendal> just my two cents, I think markdown is common, and simple enough that anyone could contribute to it. It'll be up to the docs team (or linting in CI) to double check the extensions for things like admonitions etc. All of that should be very doable
2025-08-20 13:39:16 <durrendal> if ikke hadn't have asked me to help with the user-handbook I likely would not be here to discuss any of this, antora + asciidoc coupled with a lack of activity and documentation on how/what to contribute was enough friction to prevent me from proactively contributing prior to that
2025-08-20 13:39:52 <pabloyoyoista> Then go ahead if you think that's more important :D
2025-08-20 13:39:53 <durrendal> if we can do away with all of that friction and reduce the documentation process to something common, I imagine we will have more people willing and able to contribute, much like with our wiki currently
2025-08-20 13:41:20 <durrendal> hahaha I appreciate the support, not sure that I'm the one who gets to call the shots :)
2025-08-20 13:42:44 <ikke> To me, the distinction is between technically a better solution versus more aproachable
2025-08-20 13:43:07 <ikke> (assuming the MD extensions don't make it less approachable)
2025-08-20 13:43:32 <ikke> I don't have a strong preference myself
2025-08-20 13:44:17 <ikke> Someone who just assumed the syntax was MD: https://gitlab.alpinelinux.org/alpine/docs/user-handbook/-/merge_requests/24#note_532041
2025-08-20 13:44:39 <durrendal> antora is definitely a bells and whistles included tool. It's neat, but there hasn't been a lot of active contribution on the docs repo since the contributors who set it up left
2025-08-20 13:45:23 <pabloyoyoista> I have no idea of why people wouldn't contribute to alpine docs before :) durrendal I'm only going to contribute to governance and processes, so if others don't care, maybe you indeed call the shots :P
2025-08-20 13:46:01 <ikke> I think docs.a.o itself has not that much visibility
2025-08-20 13:47:10 <durrendal> LOL well I noticed our developer handbook is literally an empty page, so I was hoping to do that if the user-handbook stuff was well received.
2025-08-20 13:47:49 <durrendal> ikke: yeah I honestly hadn't seen it before you pinged me, I've always just referred to the wiki
2025-08-20 13:47:57 <ikke> I did add some issues about things that should be documented: https://gitlab.alpinelinux.org/alpine/docs/developer-handbook/-/issues
2025-08-20 13:48:32 <ikke> So promoting docs.a.o could help, as well as make it more visible how to contribute to the documentation
2025-08-20 13:49:34 <durrendal> I had noticed those, specifically the what it means to be a maintainer, would be really nice to have something to point people to when they ask questions or there are issues.
2025-08-20 13:50:13 <durrendal> It wouldn't be hard to convert adoc to markdown if we wanted to just work on the content first while we look at different tooling
2025-08-20 13:53:41 <ikke> pabloyoyoista: I've left feedback on https://gitlab.alpinelinux.org/alpine/infra/alpine-mksite/-/merge_requests/107
2025-08-20 14:00:51 <achill> this is my WIP draft for a new developer handbook: https://pad.nixnet.services/alpine-packaging?view
2025-08-20 14:01:38 <achill> its mostly TODO stuff that i catched by reviewing stuff but i hope to write things down once i have a bit more time
2025-08-20 14:04:44 <durrendal> just skimmed it very briefly, it looks like a great start :)
2025-08-20 14:05:09 <durrendal> also, markdown I assume since it's hedgedoc?
2025-08-20 14:06:39 <achill> yeah but i mean i dont have any strong opinions on that. i just want a reference documentation for developers :))
2025-08-20 14:13:36 <durrendal> 100% agreed there, we really need something firm we can point people back to
2025-08-20 14:14:20 <durrendal> any issues if I use what you have thus far as a springboard?
2025-08-20 14:30:11 <pabloyoyoista> ikke: got one doubt with one of the feedback points. Let me know if you want to discuss it. And thanks a lot for the other feedback, specially the wording about "maintainers"
2025-08-20 14:36:16 <durrendal> ikke: is there a reason why the user/developer handbook and governance docs aren't just part of alpine-mksite?
2025-08-20 15:12:26 <ikke> durrendal: different concerns, and alpine-mksite isn't really suitable for documentation
2025-08-20 15:12:30 <ikke> pabloyoyoista: sure
2025-08-20 15:16:49 <pabloyoyoista> ikke: so what do you want me exactly to reflect in https://gitlab.alpinelinux.org/alpine/infra/alpine-mksite/-/merge_requests/107#note_534496 ? It should reflect your opinions, not mine, but I didn't really get what I should change
2025-08-20 15:20:42 <mio> interested in helping with drafting for the developer handbook, if help is still needed for remaining items in the issues list :) (e.g. is #2 partially covered by tsc's maintainers.md? is the idea to expand on existing related docs and bring them into the handbook?)
2025-08-20 15:25:44 <durrendal> would love an extra hand mio :) 
2025-08-20 15:26:26 <durrendal> A single source of truth that we could direct people interested in being maintainers, or use to centrally discuss/modify existing processes would be my intent.
2025-08-20 15:26:45 <ikke> The TSC project is not really a good place for that kind of documentation, so having it (or at least linking to it) in the developers handbook would be an improvement. Right now there are various places where things are documented which can be difficult to find
2025-08-20 15:27:24 <durrendal> like the #maintainer vs maintainer= thing, if that would come up as an issue in the docs of the handbook instead of just through IRC/individual MRs that would be a better community exerience.
2025-08-20 15:30:00 <mio> thanks :) looking forward to working with other contributors to fill in gaps where needed
2025-08-20 15:31:19 <mio> okay, it will collect up existing documentation, sounds good
2025-08-20 15:56:45 <achill> durrendal: i also try to regulary push to the alpine-devel and alpine-users mailing lists new things our packagers need to know e.g. the cmake3.5, gcc15 and stuff
2025-08-20 15:57:00 <achill> (or where we could use more hands like with the gcc15 stuff)
2025-08-20 15:57:25 <achill> not sure if thats the best place tho, maybe a alpine-devel-announce list where people can subscribe RSS to or something?
2025-08-20 15:58:32 <achill> "any issues if I use what you have thus far as a springboard?" sure go for it
2025-08-20 15:59:25 <achill> mio: in my pad link i have a few resources inside <!-- --> that i wanted to replace/extend/remove
2025-08-20 16:01:40 <mio> achill: okay, thanks! will have a look
2025-08-21 18:31:13 <oldmantux> is there anyone who can explain why there is mentioned a developer handbook on the alpine linux documentation site (e.g. at the user handbook) that does not exist but  is referenced multiple time ?
2025-08-21 18:31:53 <oldmantux> here the missing s for .... multiple TIMES ...
2025-08-21 19:23:12 <durrendal> drat they left before I saw that
2025-08-21 19:24:21 <durrendal> oldmantux, in the off chance you check the channel logs, the short answer is that we're currently working on write those documents.
2025-08-21 19:24:30 <ikke> fyi, it was also posted in #alpine-linux
2025-08-21 19:28:05 <durrendal> I didn't notice that, thanks for mentioning it
2025-08-22 04:32:55 <durrendal> https://gitlab.alpinelinux.org/alpine/docs/docs.a.o/-/issues/5 <- dropping this here before I head off to bed. Would really appreciate feedback/concerns about migrating to mkdocs.
2025-08-22 04:33:34 <durrendal> It wasn't difficult to convert the existing adoc to md, and mkdocs supports admonitions, styling etc. I think it's a viable option
2025-08-22 04:34:10 <durrendal> the rapidity with which I was able to take what we had and move it over to mkdocs speaks volumes about the simplicity of it as a solution.
2025-08-22 08:28:37 <ncopa> im super happy to see movement here
2025-08-22 08:31:02 <ncopa> mio: do you have any opinion on adoc vs markdown (mkdocs)?
2025-08-22 08:32:08 <ikke> Yes, me too
2025-08-22 08:33:30 <ncopa> durrendal: I have been thinking of migrating alpine-mksite to hugo. If that ever happens it would be doable to have the docs together with the main site - if we'd want that
2025-08-22 08:33:36 <ncopa> but i dont know if we want that
2025-08-22 08:39:28 <ikke> If we keep them separate, it's easier to give more people permissions to merge things
2025-08-22 08:40:12 <ikke> To me the www.a.o and docs.a.o serve different purposes
2025-08-22 08:40:25 <ncopa> *nod*
2025-08-22 08:40:42 <ncopa> i suppose hugo is an alternative to mkdocs
2025-08-22 08:40:50 <ikke> yes, we have looked at that
2025-08-22 08:40:58 <ncopa> and the conclusion?
2025-08-22 08:41:44 <ikke> mkdocs would work a bit better, specifically if we want to be able to keep separate documentation per version
2025-08-22 08:42:18 <ncopa> how does mkdocs handle that? isn't it just a question of git branches?
2025-08-22 08:42:33 <ncopa> spearate docs per version sounds like a good idea to me
2025-08-22 08:42:41 <ncopa> ah, i get it
2025-08-22 08:42:59 <ncopa> yeah, makes sense
2025-08-22 12:14:25 <durrendal> No problem at all, I've been mulling the idea since ikke pinged me to help with the user-handbook initially. Might as well be the change you want to see right?
2025-08-22 12:15:34 <durrendal> I had also thought to roll the user documentation into alpine-mksite, but ikke's point is valid. www.a.o is the distro site, docs.a.o is official documentation. They're separate audiences
2025-08-22 12:16:22 <durrendal> But if we move to a md backed system we get the flexibility to more easily merge those documents/sites together if there's a future desire to do so. 
2025-08-22 12:18:46 <durrendal> For mkdocs versioning the general suggestion is to use the mike plugin
2025-08-22 12:18:49 <durrendal> https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
2025-08-22 12:19:13 <ikke> ack
2025-08-22 12:24:21 <ikke> It does seem that mike has a default expectation of publishing to github pages
2025-08-22 12:25:36 <ikke> (and thus adding the documentation in a gh-pages branch
2025-08-22 12:26:35 <achill> do we need versioning, a note in the docs with "earlier than 3.xx: use this instead" would be fine imo. older docs might also lack quality and quantity than master
2025-08-22 12:27:09 <achill> at least for the developer docs, i'd rather avoid versioning
2025-08-22 12:27:21 <ikke> yeah, this is more for user-docs
2025-08-22 12:27:23 <ikke> not developer
2025-08-22 13:21:43 <mio> ncopa: on adoc vs. md, adoc has more features, which some tech writers might like. for starters, it may better to try a format more people might be familiar with, to lower friction for contributions
2025-08-22 13:22:25 <mio> it should be possible to automate the format conversion from md -> adoc if need be later
2025-08-22 14:02:21 <ncopa> yeah, thats what I figured. I wonder if you have any personal preference
2025-08-22 14:03:15 <ncopa> i just dont want to end up with a situation where we push for markdown while majority of the people doing the work preferring adoc
2025-08-22 14:04:31 <ikke> Would be good to add your opinion to the issue that durrendal created
2025-08-22 14:04:43 <mio> there are features to like about adoc, for me it's not a hard blocker either way
2025-08-22 14:06:06 <mio> will do
2025-08-22 14:06:20 <durrendal> for what it's worth, I agree emphatically with ncopa, just because I feel mkdocs is a viable solution does not mean it is the best solution.
2025-08-22 14:06:52 <durrendal> I would be more than happy to spin up other comparisons if someone feels strongly about any particular system
2025-08-22 14:10:11 <ncopa> my thinking is, that we need volunteers working on the docs. markdown *may* make it easier for people to contribute. But it is not a guarantee
2025-08-22 14:10:59 <ikke> https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/
2025-08-22 14:11:11 <ikke> (ofcourse, onesided comparisson
2025-08-22 14:11:35 <durrendal> mio and I have been discussing that bit as well, we're going to end up needing a docs-handbook of sorts if we want to really remove friction.
2025-08-22 14:11:49 <durrendal> it's on my todo list if that helps :)
2025-08-22 14:14:08 <durrendal> yeah asciidoctor and antora are pretty much the same organization. It's like Hashicorp saying "look how good hcl is as a language compared to Ansible's yaml|jinja"
2025-08-22 14:14:19 <ikke> :)
2025-08-22 14:14:44 <durrendal> a lot of the features they mark as unsupported by markdown are supported by plugins in mkdocs, and I would bet hugo or sphinx have similar support
2025-08-22 14:15:11 <ikke> "Here’s how the story inevitably goes. You start out with Markdown. Then it’s Markdown + X. Then Markdown + X + Y" :P
2025-08-22 14:15:57 <ikke> The argument goes that once you start adding plugins, it's no longer markdown and the benefit of using markdown goes down
2025-08-22 14:31:46 <durrendal> I feel like that's a bit of false equivalence. adoc by itself isn't going to do the things it says it does without a thing to render it
2025-08-22 14:32:28 <durrendal> comparing antora/mkdocs/hugo/sphinx as build systems for documentation is a fair comparison though
2025-08-22 14:33:18 <durrendal> I guess phrased another way I think of it like docker. That's a simplified method to deploy a service, something that would traditionally require systems administration knowledge.
2025-08-22 14:33:30 <durrendal> dockerfile <-> markdown
2025-08-22 14:34:10 <durrendal> without the tool on top to make them useful, they're just text. If I build CI/CD and have an infra/docs team to ensure that the technically complex stuff works then all anyone has to contribute is words
2025-08-22 14:34:29 <durrendal> keeping the syntax for that as simple as possible lowers the bar to entry
2025-08-22 14:38:09 <ikke> This is more like saying: everyone if familiar with Dockerfiles, so we should use that, but we also want to add extend the Dockerile syntax.
2025-08-22 14:38:18 <ikke> s/add/
2025-08-22 14:44:53 <durrendal> valid point, I think my counter argument would be that people are generally familiar with markdown and the contributions to the wiki + TSC documentation emphasize that point. Plus people interact with it passively while using Gitlab
2025-08-22 14:46:10 <durrendal> I've never seen asciidoc implemented anywhere until looking into this. It seems to be a tool geared towards writing technical documentation built for documentation teams. But this could just be my experience as a devops engineer where everything is yaml because it's the simplest shared syntax
2025-08-22 14:46:54 <durrendal> ie: that's where my head is at. markdown makes sense in the same way I feel yaml makes sense
2025-08-22 14:48:13 <ncopa> i did asciidoc a decade+ ago. I set up some makefiles to generate PDFs that looked like they were writtes in MS word
2025-08-22 14:50:18 <ncopa> we use markdown in gitlab and I expect people are used to markdown from upstream/other projects (in github)
2025-08-22 14:52:10 <ncopa> and we use markdown for alpine-mksite
2025-08-22 14:53:37 <pabloyoyoista> If alpine does not need the extra antora features, and the missing adoc pieces can be filled with extensions, then mkdocs, no? Is there anybody that was advocating for Antora than myself? If not, you got me convinced :P Go and move it to mkdocs :D
2025-08-22 15:04:01 <durrendal> pabloyoyoista: even if you are the only person advocating for antora, I don't want to make an organization change based entirely off of what I think is good :)
2025-08-22 15:04:19 <durrendal> so yes, having your approval is both welcomed and necessary
2025-08-22 15:05:02 <durrendal> ncopa: perhaps I'm just in the minority then, I've talked to a couple of friends who are technical writers professionally and they have pointed to antora as a standard tool for this type of work
2025-08-22 15:10:44 <pabloyoyoista> Yeah, but seems everybody else thinks mkdocs is a good idea. And to me it seems to fit what alpine needs. Usually the lowest-complexity tool that does the work is the best one :)
2025-08-22 15:31:48 <ncopa> "Usually the lowest-complexity tool that does the work is the best one" I love this sentence
2025-08-22 15:32:18 <durrendal> we are a minimalistic distribution, it's a good mindset to have
2025-08-22 17:18:32 <sliwkr> Hello, sharing a docs MR for review at abuild https://gitlab.alpinelinux.org/alpine/abuild/-/merge_requests/429 
2025-08-22 19:23:55 <durrendal> sliwkr: thanks for mentioning it! I left some comments with some suggestions :)
2025-08-22 19:27:21 <sliwkr> Thanks, will amend as suggested
2025-08-23 12:23:52 <vkrishn> Read, archlinux wiki strategy - https://lwn.net/Articles/1032604/ (@ikke, thanks for link),
2025-08-23 12:24:09 <vkrishn> principles here are quite nicely put, I have tried to experiment by
2025-08-23 12:24:17 <vkrishn> breaking into understadable paragraphs, so pills can be added(read next)
2025-08-23 12:24:30 <vkrishn> ... moment :)
2025-08-23 12:24:53 <vkrishn> about "verified" template:
2025-08-23 12:24:59 <vkrishn>  - as pointed out in (2025-08-15 09:53:18 - https://alpine.insteps.net/irclogs/alpine/docs.php?dt=15), 
2025-08-23 12:25:31 <vkrishn>  - sounds nice, be as argued later it would loose relevance over period(obsolence)
2025-08-23 12:25:40 <vkrishn>  - but this can be experimented with verified+version
2025-08-23 12:26:00 <vkrishn>  - not easy, but gap can be closed.
2025-08-23 12:26:25 <vkrishn>  - This can be tried "in Walkthrough pages" for simple setups,
2025-08-23 12:26:41 <vkrishn>  - example, https://alpine.insteps.net/wiki/index.php?title=LXC_Alpinelinux_Simple
2025-08-23 12:28:32 <vkrishn>  - this page uses template pills and modified box
2025-08-23 12:28:36 <vkrishn>    (alternate suggestion: pills, badge, bubble, puff, vinfo, nugget, pez, gem)
2025-08-23 12:29:06 <vkrishn>  - TODO: layout check in various browsers, and mobiles devices for redering
2025-08-23 12:32:26 <vkrishn> @ikke, @prabu let me if sounds' useful, I read irc-logs even when not logged here
2025-08-23 12:32:46 <vkrishn> If this needs putting in gitlab issues pages, I can re-draft it. :)
2025-08-23 13:14:18 <sliwkr> durrendal: applied your suggestions :) https://gitlab.alpinelinux.org/alpine/abuild/-/merge_requests/429
2025-08-23 13:17:15 <sliwkr> ... and just noticed Sertonix response
2025-08-23 13:58:11 <vkrishn> correction above: templates used are Cmd, Verified, Pill
2025-08-23 13:58:27 <vkrishn> modified templates for ref, Pill: https://tpaste.us/VYra , Cmd: https://tpaste.us/melE 
2025-08-25 13:01:06 <vkrishn> managed to wake my dormant wiki.a.o account
2025-08-25 13:01:19 <vkrishn> thinking of starting a series of pages(walkthrough) type, draft seems ok,
2025-08-25 13:01:28 <vkrishn> have a look at, https://alpine.insteps.net/wiki/index.php?title=Qemu-simple and
2025-08-25 13:01:42 <vkrishn> https://alpine.insteps.net/wiki/index.php?title=LXC_Alpinelinux_Simple
2025-08-25 13:07:29 <vkrishn> any thoughts on using git for wiki.a.o, what are complexities involved?
2025-08-25 13:07:41 <vkrishn> pmOs does it (currently stopped updating its git repo, iirc)
2025-08-25 13:08:57 <vkrishn> achill: about, https://pad.nixnet.services/alpine-packaging?view, would it make sense to
2025-08-25 13:09:00 <vkrishn>  - add "provide hello-world skel in aports or somewhere", for C, Rust, Python ... etc
2025-08-25 13:14:15 <achill> i geniuly dont understand what you mean
2025-08-25 13:14:35 <achill> also postmarketos doesn't mirror the wiki to a git repository and i dont understand the benefits doing so
2025-08-25 13:15:10 <achill> (than just having a seperate documentation repository which gets publushed seperately, and is properly reviewed etc)
2025-08-25 13:18:16 <Ermine> mckaygerhard v2?
2025-08-25 13:19:09 <Ermine> (he posts transphobic shit now in his alpine tg channel btw)
2025-08-25 13:22:10 <vkrishn_> skel = skeleton for APKBUILD samples for hello world application, for C, Rust, Go, Py
2025-08-25 13:23:46 <vkrishn_> not mirroring wiki is ok, was trying to get pro/cons on doing it
2025-08-25 13:34:25 <vkrishn> Walkthrough series pages for newbie users
2025-08-25 13:34:35 <vkrishn> - idea here is to make sure they have gone through these pages and have a basic setup, before asking more adavanced questions on IRC.
2025-08-25 13:35:07 <vkrishn> - alt name, "get me started", "howto basics", "dummies on .."
2025-08-25 13:38:08 <vkrishn> - version tag/pill on it would ensure it "works atleast in some version"
2025-08-25 13:39:37 <ikke> vkrishn: FYI, docs.a.o is the primary source for that kind of introduction
2025-08-25 13:45:21 <vkrishn> ok, then will keep keyword "walkthrough+simple"
2025-08-25 13:46:48 <vkrishn> ikke: were you able to access my draft pages? 
2025-08-25 13:53:00 <vkrishn> domain runs on dynamic ip
2025-08-25 14:05:27 <durrendal> vkrishn: we're currently working to update the official documentation with that sort of information. There are a few MRs and several issues open under docs.a.o and its subrepos if you're interested
2025-08-25 14:13:27 <vkrishn> sounds nice, the skel^ part can likely go in docs.a.o (maybe in new developer_handbook)
2025-08-25 14:16:29 <vkrishn> or in git.a.o aports under folder skel, which does not get build by builders
2025-08-25 14:17:17 <durrendal> just to confirm I'm tracking, you're talking about template files for various types of APKBUILDs and not usage of /etc/skel/ right?
2025-08-25 14:19:40 <vkrishn> skel = skeleton for APKBUILD samples for hello world application, for C, Rust, Go, Py
2025-08-25 14:21:58 <durrendal> https://wiki.alpinelinux.org/wiki/APKBUILD_examples <- we currently have this page which has examples of various packaging patterns
2025-08-25 14:23:15 <durrendal> Perhaps it's worth a look? I do think some of that type of content may end up in the developers handbook ffiw
2025-08-25 14:23:28 <vkrishn> yes, idea of skel, is point newbies to it, git clone it, build skel and get a hang of it
2025-08-25 14:24:20 <durrendal> Oh I think I'm tracking, like a little training repo of how abuild works with known working and tested simple samples
2025-08-25 14:24:35 <vkrishn> devs are not users(in some way) ;)
2025-08-25 14:25:01 <vkrishn> wiki is for users(primarily)
2025-08-25 14:49:30 <vkrishn> and for users, the walkthrough pages on wiki.a.o
2025-08-25 14:50:46 <vkrishn> idea is, get through these section, then ask more questions
2025-08-25 15:04:57 <vkrishn> this idea stems from https://lwn.net/Articles/1032604/ "not offer too much hand-holding"
2025-08-25 15:05:40 <vkrishn> + DRY principle
2025-08-25 15:23:28 <pabloyoyoista> ikke: regarding https://gitlab.alpinelinux.org/alpine/infra/alpine-mksite/-/merge_requests/107#note_535071 is there a place where it's documented how is the current site deployed?
2025-08-25 15:23:40 <pabloyoyoista> I'm a bit confused because local testing of "latest" works
2025-08-25 15:24:38 <ikke> pabloyoyoista: this is the script executed by mqtt-exec: https://tpaste.us/9XaP 
2025-08-25 15:34:08 <vkrishn> created 2 pages, https://wiki.alpinelinux.org/wiki/Qemu-simple, https://wiki.alpinelinux.org/wiki/LXC_Alpinelinux_Simple
2025-08-25 15:35:05 <vkrishn> will add them to Tutorials_and_Howtos under new section Walkthrough: , soonish
2025-08-25 15:39:38 <pabloyoyoista> ikke: strange. I have built locally also with the production site.yml and it automatically redirects to latest
2025-08-25 15:41:26 <pabloyoyoista> Could it be that the deployment failed in some way/
2025-08-25 15:41:30 <pabloyoyoista> s///?/
2025-08-25 17:26:50 <ikke> pabloyoyoista: rand the command again by hand, no errors
2025-08-25 17:27:05 <ikke> ah
2025-08-25 17:28:15 <ikke> pabloyoyoista: error: configuration param 'urls.latest_version_segment' not declared in the schema
2025-08-25 17:29:56 <ikke> pabloyoyoista: the container still uses antora 2.0
2025-08-25 18:15:34 <pabloyoyoista> Ah, interesting. Any chance it can be updated to use antora from https://gitlab.alpinelinux.org/alpine/infra/docker/antora ?
2025-08-25 19:02:53 <fabricionaweb>  https://wiki.alpinelinux.org/wiki/LXC_Alpinelinux_Simple > under "Install LXC and its dependencies", is it bridge or lxc-bridge?
2025-08-25 19:06:46 <vkrishn> on my test machine, i have https://tpaste.us/nNlV 
2025-08-25 19:07:05 <ikke> lxc-bridge is configuration for dnsmasq
2025-08-25 19:07:11 <vkrishn> and bridge is also installed
2025-08-25 19:07:51 <vkrishn> I think i would leave dhcp for later adv pages
2025-08-25 19:12:33 <pabloyoyoista> ikke: should I push back the developers blog post one or two days, or maybe more like a week? I understand this antora deployment might not have priority, so you tell me :)
2025-08-25 19:41:19 <vkrishn> fabricionaweb: fixed some missing cmds, `brctl addbr br0` is needed to be set before (updated on page now)
2025-08-25 19:41:48 <vkrishn> will do a clean test and remove Draft tag
2025-08-25 20:00:14 <vkrishn> i think 'bridge' is not needed for this setup, will re-check
2025-08-27 12:25:50 <pabloyoyoista> ncopa: any chance you can merge https://gitlab.alpinelinux.org/alpine/infra/alpine-mksite/-/merge_requests/107 today?
2025-08-27 14:31:35 <ncopa> done! thanks!
2025-08-27 14:54:43 <pabloyoyoista> Cool! Do  you want to post on Mastodon? Or should I?
2025-08-27 15:02:46 <durrendal> pabloyoyoista: I noticed a typo, and 50 new merge requests make it aports (with peaks of over 100 MRs a day).
2025-08-27 15:03:07 <durrendal> not a blocker, just wanted you to be aware.
2025-08-27 15:04:44 <pabloyoyoista> It's already merged, wanna send an MR?
2025-08-28 20:08:09 <vkrishn> added https://wiki.alpinelinux.org/wiki/Simple_Walkthrough , a guide on about+howto on walk-through pages
2025-08-28 20:14:35 <Ermine> 1) this project is called Alpine Linux, not Alpinelinux
2025-08-28 20:23:27 <vkrishn> ok, will change
2025-08-28 20:23:40 <vkrishn> alpinelinux.org should be alpine-linux
2025-08-28 20:25:59 <vkrishn> change wiki page name LXC_Alpinelinux_Simple to LXC_Alpine_Linux_Simple ?
2025-08-28 20:28:51 <vkrishn> done, thanks
2025-08-28 20:28:59 <Ermine> "LXC Alpine Linux Simple" to that matter, but this title stil doesn't make any sense
2025-08-28 20:30:45 <vkrishn> suggest?
2025-08-28 20:37:53 <vkrishn> done on other pages too
2025-08-28 20:42:16 <vkrishn> haven't added those pages to https://wiki.alpinelinux.org/wiki/Tutorials_and_Howtos , will leave it a day or 2
2025-08-28 21:04:04 <vkrishn> I recall why I did LXC_Alpinelinux_Simple, while going through LXC page, I thought of spliting it into LXC, LXC_Debian, LXC_Ubuntu, then started simple pages and called it LXC_Alpinelinux_Simple
2025-08-28 21:06:03 <vkrishn> still have those rough cut pages in my local wiki
2025-08-29 13:47:39 <Sertonix[m]> Is https://wiki.alpinelinux.org/wiki/Raspberry_Pi#Wireless_support_with_older_Alpine_images still relevant for any supported alpine version? Otherwise I would recommend to remove it