16:02:28 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:02:28 <samccann> @room Meeting time! Who is here to talk the docs?
16:02:28 <zodbot> Meeting started Tue Mar 21 16:02:28 2023 UTC.
16:02:28 <zodbot> This meeting is logged and archived in a public location.
16:02:28 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:02:28 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:02:28 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:03:02 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
16:03:09 <oranod> hey samccann and all
16:03:12 <oranod> o/
16:03:21 <ariordan> o/
16:03:21 <felixfontein> o/
16:03:28 <samccann> #chair felixfontein Don Naro ariordan
16:03:28 <zodbot> Current chairs: Don Naro ariordan felixfontein samccann
16:03:33 <samccann> welcome welcome~
16:03:43 <samccann> To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link)
16:03:52 <samccann> General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!)
16:04:06 <samccann> briantist: around to talk docs today?
16:04:22 <briantist> sorry, I have to miss this one 😭
16:04:37 <samccann> 😭
16:04:38 <oranod> feel like we haven't seen you in a while briantist hope all is well
16:05:02 <samccann> yeah we should have a tea n biscuits hour in docs land someday ;-) just for fun
16:05:15 <samccann> tho that's the social channel I suppose.. .so.. tea n biscuits on social!'
16:05:29 <felixfontein> #info the devel docsite should have semantic markup support from tomorrow on (https://github.com/ansible/ansible/pull/80201), and the Ansible 7 docsite will also support it
16:05:48 <samccann> woot!!!
16:05:53 <felixfontein> #info ansible-doc from ansible-core devel also supports semantic markup (https://github.com/ansible/ansible/pull/80242/files), and thus ansible-doc from ansible-core 2.15 / Ansible 7 will also do so
16:05:56 <samccann> oh wait.. that only goes to core devel
16:06:08 <samccann> woohoo!!
16:06:24 <samccann> thanks felixfontein for reviving and driving this one! So glad to see this happening
16:06:38 <felixfontein> the core devel docsite should already have used the latest antsibull-docs release anyway, shouldn't it?
16:06:51 <samccann> oh yeah sorry, doh!
16:06:54 <samccann> you're right
16:07:02 * samccann confused by too many build options
16:07:31 <samccann> Are there any more must-have prs for semantic markup before the branch pull happens next week?
16:07:36 <briantist> oranod: you're not wrong! I just have a sudden boatload of work and such, so I'm severely overloaded, for like the next month at least, and then I'll be traveling for nearly 4 weeks.. and then I'll come back to a week of work events, and then the week after that is AnsibleFest/RH Summit (which I am going to try to attend)... so yeah... 😳
16:07:51 <felixfontein> there are two (three) more outstanding PRs, https://github.com/ansible/ansible/pull/80212 to show plugin see-alsos in ansible-doc, and https://github.com/ansible/ansible/pull/80244 to make plugin see-also pass validate-modules validation
16:08:20 <felixfontein> (there's also https://github.com/ansible/ansible/pull/80243 for more extensive semantic markup linting for validate-modules, but apparently the chances for that are slim to make it in for 2.15)
16:08:48 <felixfontein> briantist: sounds like 'fun'... I hope it is more fun than it sounds :)
16:08:59 <oranod> briantist: well, best of luck with the workload and safe travels!
16:09:13 <oranod> and, yeah, hopefully it is more fun than it sounds
16:09:16 <briantist> thanks!
16:09:31 <samccann> yeah busy times for you!
16:09:36 <felixfontein> samccann: nothing is must-have, but https://github.com/ansible/ansible/pull/80212 and https://github.com/ansible/ansible/pull/80244 would make life much easier - the former to avoid hiding information from the ansible-doc output, and the latter to avoid having to ignore DOCUMENTATION syntax errors when using plugin seealsos
16:10:22 <samccann> #info https://github.com/ansible/ansible/pull/80212 and https://github.com/ansible/ansible/pull/80244 are required for 2.15 for semantic markup
16:10:44 <samccann> #info https://github.com/ansible/ansible/pull/80243 may not happen in time for 2.15 for semantic markup support
16:10:47 <samccann> coolness
16:11:11 <samccann> anything else in semantic markup land before we move on?
16:11:21 <felixfontein> I will add similar support to https://github.com/ansible/ansible/pull/80243 to antsibull-docs so you can use `antsibull-docs lint-plugin-docs` (or how it was called again) to do linting
16:11:46 <samccann> for those wondering - this is a way to mark module documentation based on the type of item (option etc) vs marking it how you want it to present (bold vs italic)
16:12:02 <felixfontein> I don't think so, that should be everything for now...
16:12:43 <samccann> felixfontein: is the antsibull-docs stuff coming before branch pull or is that a future thing, whenever the core PR merges?
16:12:59 <felixfontein> there'll be a new lean Python library  out in the open soon (like today or tomorrow) that supports handling Ansible markup with no dependencies; this can be used by other projects to add semantic markup support without having to re-implement the specs
16:13:10 <felixfontein> (there's already a TypeScript library of similar scope)
16:13:47 <felixfontein> both are currently in active development and will get some more features until their 1.0.0 releases
16:13:55 <samccann> cool
16:14:16 <samccann> #topic New docsite pages
16:14:18 <felixfontein> then there are less excuses for other projects to not support semantic markup :)
16:14:28 <samccann> haha yep!
16:14:37 <samccann> #info new docsite pages are visible at https://ansible.github.io/jinja-docsite/ - please play aorund and give us feedback
16:14:42 <felixfontein> (and now I really shut up about semantic markup ;) )
16:14:50 <oranod> lol
16:14:50 <samccann> anything you want to talk about Don Naro
16:15:19 <samccann> hey it's a major accomplishment to revive semantic markup after 2 yrs of stagnating on the RH side!
16:15:33 <felixfontein> the new docsite looks really cool!
16:15:56 <oranod> #info please consider the Ansible docsite journeys when reviewing the prototype docsite and be aware that the layout and UX for the new docsite will change after we come to a decision on the static site generator
16:16:21 <oranod> #info user journeys are here: https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md
16:16:37 <samccann> very good points!
16:16:56 <oranod> the whole point of the new docsite is to put the focus on connecting Ansible users with information at the right stage of their journey
16:17:37 <oranod> those user journeys will continue to evolve and expand out to other projects in the Ansible ecosystem and this new docsite is the first step towards that more journey-focused approach
16:18:10 <oranod> thanks felixfontein we're getting close to the MVP for the new docsite and there's one thing I might ask you to review
16:18:21 <samccann> woot!
16:18:45 <samccann> do we want to post it to things other than the bullhorn now? like reddit? mastodon etc?
16:19:01 <oranod> #info I could def use some extra review on the JS I'm using for A/B testing https://github.com/ansible/jinja-docsite/issues/20
16:19:02 <felixfontein> oranod: sounds good! the more specific it is what I should review the more I can promise I can actually manage to do it ;)
16:19:05 <samccann> or any branches we need to rattle in the RH tree?
16:19:36 <oranod> felixfontein: I'll ping you in the PR. not sure how much you like javascript though...
16:20:05 <felixfontein> oranod: I don't like it, but I can read and write it ;) (I really prefer TypeScript...)
16:20:09 <oranod> samccann: once we have our MVP I think it'd be a good idea to post it in Reddit and maybe somewhere else
16:20:37 <samccann> ok makes sense
16:20:50 <oranod> I've only used typescript a bit for a react console I contributed
16:20:54 <oranod> * I contributed to
16:21:02 <samccann> #info once we have MVP issues fixed we can bring in more reviewers to the docsite prototype before it goes live
16:21:30 <oranod> thanks to everyone who has provided feedback so far and all the discussions here
16:22:02 <samccann> #info help needed on some issues on that new docsite - https://github.com/ansible/jinja-docsite/issues
16:22:13 <samccann> for those reading the minutes ;-)
16:22:28 <samccann> Anything else you want use doing/looking at/thinking about?
16:22:57 <oranod> not sure it belongs here but we could highlight the SSG topic
16:23:04 <samccann> #info use the prototype website to explore the user/contributor/developer journeys presented there. This is our first iteration of changing how our readers explore ansible docs
16:23:21 <samccann> go ahead Don Naro
16:24:32 <oranod> #info we've identified a set of requirements and potential candidates for the static site generator that we'll use to build a new Ansible community website (after the vote closes) as well as the new docsite. details are here: https://github.com/ansible-community/community-topics/issues/210
16:24:56 <samccann> ...and vote closes today i think :-)
16:25:13 <oranod> yeah I think so
16:25:43 <samccann> website discussion - https://github.com/ansible-community/community-topics/issues/201
16:25:46 <samccann> in case anyone wants to read up and then vote.
16:26:24 <samccann> from a docs perspective, we'll be part of that new website over time.
16:27:14 <oranod> so for that SSG topic I've added some entries and thoughts on the different options and am trying to chase down input from other folks who have put forward recommendations like Lektor and MkDocs. it'd be great to have more opinions on it and I wanted to highlight that here.
16:27:52 <oranod> I hope that we can narrow it down to two or three candidates based on the requirements checklist then put it to a vote
16:30:52 <oranod> I feel like it will probably come down to Nikola, MkDocs, and Lektor - the best choice seems to be whatever can help us get off the ground fast without too much customization, low barrier for other contributors, and nothing too complex.
16:31:50 <samccann> can mkdocs support multiple pages before the docs? I saw  what someone pointed to and the front page is nice, but we'd need I'd say 1/2 dozen pages like that
16:33:18 <oranod> I believe so, yeah. ssbarnea probably knows MkDocs the best.
16:34:05 <oranod> it's a little like Sphinx in the sense that MkDocs is best known for documentation not websites but it is possible
16:34:20 <samccann> ok cool. that was the only one that caught my eye because of what you just said lol
16:34:59 <oranod> it also seems like MkDocs has some momentum behind it that Sphinx doesn't so I do like it for that
16:36:05 <oranod> almost like it's in this sweet spot where MkDocs has some of the more modern bells and whistles that you'd see in Hugo while also already in use for several Ansible projects
16:36:37 <samccann> yeah that's a bennie
16:37:21 <oranod> a bennie?
16:37:56 <zbr> My WIP document on mkdocs can be visited at https://hackmd.io/@42/mkdocs-ansible
16:38:00 <samccann> benefit... lazy typer
16:38:31 <zbr> is not all green on the other side, but to me it looks much greener than sphinx
16:38:36 <samccann> thanks ssbarnea ..I'll take a look after the meeting. looks good
16:38:39 <felixfontein> does mkdocs also supports blogs?
16:39:12 <felixfontein> (nikola and lector both support blogs)
16:39:32 <zbr> felixfontein: kind of, blogs feature is paid right now but will become free soon, also there is another free plugin for rss but i did not try it.
16:40:01 <felixfontein> do you know when soon will be?
16:40:21 <zbr> in fact that is the only reason why I did no convert my personal site to mkdocs yet, even if I suspect that "rss" use might be very low.
16:41:41 <zbr> have a look at https://squidfunk.github.io/mkdocs-material/insiders/#:~:text=Material%20for%20MkDocs%20Insiders%20is,made%20collaborators%20of%20this%20repository.
16:42:28 <zbr> mkdocs-material has a very interesting business model that is quite transparent. basically they mention when features become free based on level of sponsoring reached.
16:42:51 <zbr> you can start using the "insiders" features at any time if you are a sponsor.
16:43:04 <zbr> i suspect that they will reach the next goal in less than 6mo
16:43:44 <zbr> but we can also look at the other plugins too, is just that i did not had time
16:44:06 <samccann> so if Ansible paid, we'd have blog support today?
16:44:14 <zbr> i would prefer to use material because I know that is very well maintained and supported
16:44:21 <zbr> yes, we can.
16:44:27 <samccann> ok good to know
16:44:38 <zbr> and my plan was to become official sponsor at some point
16:44:59 <zbr> for now I am only sponsoring him personally
16:45:16 <samccann> ok meanwhile in docs land...
16:45:28 <samccann> #topic Open Floor
16:45:28 <samccann> anything docs related we want to discuss?
16:45:30 <oranod> 🕺
16:45:38 <oranod> open dance floor
16:45:41 <samccann> hahah
16:46:13 <felixfontein> hmm, do I understand it correctly that blog support for mkdocs is provided by a specific *mkdocs theme*?
16:46:18 <samccann> #info vote on the forum topic - https://github.com/ansible-community/community-topics/discussions/211
16:46:33 <zbr> the theme comes with its own plugins, blog being one of them.
16:46:55 <zbr> but you could use/write another plugin to obtain similar functionality
16:47:12 <zbr> think about material theme as bundle
16:47:26 <felixfontein> could you use the plugins coming with that theme with another theme? or does it mean if you start using the blog functionality there, you cannot change themes anymore?
16:48:31 <zbr> yeah, you can mix and match, but not all play along well. i found some conflicts especially related to monorepo plugin
16:48:58 <zbr> to give some insghts, 'monorepo' plugin is the one that allows you to combine multiple mkdocs sites into a single one, the most mature one.
16:49:20 <zbr> there are two other ones but i was not able to make them  work for me, only that one looked ok.
16:49:39 <felixfontein> ok, thanks!
16:49:45 <zbr> This is a page/repo that should be watched, is updated every month
16:49:51 <zbr> https://github.com/pawamoy/best-of-mkdocs
16:50:04 <zbr> gives a good idea about trending up or down in mkdocs ecosystem
16:50:34 <zbr> as expected, not all components are maintained so well
16:51:14 <zbr> but I was glad that he theme was, especially as most Ansible contributors are not UX/HTML/CSS designers.
16:51:33 <zbr> most of us are good at python, but not web stuff
16:51:46 <oranod> the web stuff is dark magic
16:52:02 <zbr> I was more inclined to say 'brownish'
16:52:13 <oranod> lol
16:54:38 <oranod> I need to take a quick break before the next meeting starts up.
16:54:51 <oranod> thanks samccann
16:56:08 <samccann> yep
16:56:13 <samccann> #endmeeting