16:02:28 #startmeeting Documentation Working Group aka DaWGs 16:02:28 @room Meeting time! Who is here to talk the docs? 16:02:28 Meeting started Tue Mar 21 16:02:28 2023 UTC. 16:02:28 This meeting is logged and archived in a public location. 16:02:28 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 16:02:28 Useful Commands: #action #agreed #halp #info #idea #link #topic. 16:02:28 The meeting name has been set to 'documentation_working_group_aka_dawgs' 16:03:02 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 hey samccann and all 16:03:12 o/ 16:03:21 o/ 16:03:21 o/ 16:03:28 #chair felixfontein Don Naro ariordan 16:03:28 Current chairs: Don Naro ariordan felixfontein samccann 16:03:33 welcome welcome~ 16:03:43 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 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 briantist: around to talk docs today? 16:04:22 sorry, I have to miss this one 😭 16:04:37 😭 16:04:38 feel like we haven't seen you in a while briantist hope all is well 16:05:02 yeah we should have a tea n biscuits hour in docs land someday ;-) just for fun 16:05:15 tho that's the social channel I suppose.. .so.. tea n biscuits on social!' 16:05:29 #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 woot!!! 16:05:53 #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 oh wait.. that only goes to core devel 16:06:08 woohoo!! 16:06:24 thanks felixfontein for reviving and driving this one! So glad to see this happening 16:06:38 the core devel docsite should already have used the latest antsibull-docs release anyway, shouldn't it? 16:06:51 oh yeah sorry, doh! 16:06:54 you're right 16:07:02 * samccann confused by too many build options 16:07:31 Are there any more must-have prs for semantic markup before the branch pull happens next week? 16:07:36 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 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 (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 briantist: sounds like 'fun'... I hope it is more fun than it sounds :) 16:08:59 briantist: well, best of luck with the workload and safe travels! 16:09:13 and, yeah, hopefully it is more fun than it sounds 16:09:16 thanks! 16:09:31 yeah busy times for you! 16:09:36 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 #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 #info https://github.com/ansible/ansible/pull/80243 may not happen in time for 2.15 for semantic markup support 16:10:47 coolness 16:11:11 anything else in semantic markup land before we move on? 16:11:21 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 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 I don't think so, that should be everything for now... 16:12:43 felixfontein: is the antsibull-docs stuff coming before branch pull or is that a future thing, whenever the core PR merges? 16:12:59 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 (there's already a TypeScript library of similar scope) 16:13:47 both are currently in active development and will get some more features until their 1.0.0 releases 16:13:55 cool 16:14:16 #topic New docsite pages 16:14:18 then there are less excuses for other projects to not support semantic markup :) 16:14:28 haha yep! 16:14:37 #info new docsite pages are visible at https://ansible.github.io/jinja-docsite/ - please play aorund and give us feedback 16:14:42 (and now I really shut up about semantic markup ;) ) 16:14:50 lol 16:14:50 anything you want to talk about Don Naro 16:15:19 hey it's a major accomplishment to revive semantic markup after 2 yrs of stagnating on the RH side! 16:15:33 the new docsite looks really cool! 16:15:56 #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 #info user journeys are here: https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md 16:16:37 very good points! 16:16:56 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 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 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 woot! 16:18:45 do we want to post it to things other than the bullhorn now? like reddit? mastodon etc? 16:19:01 #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 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 or any branches we need to rattle in the RH tree? 16:19:36 felixfontein: I'll ping you in the PR. not sure how much you like javascript though... 16:20:05 oranod: I don't like it, but I can read and write it ;) (I really prefer TypeScript...) 16:20:09 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 ok makes sense 16:20:50 I've only used typescript a bit for a react console I contributed 16:20:54 * I contributed to 16:21:02 #info once we have MVP issues fixed we can bring in more reviewers to the docsite prototype before it goes live 16:21:30 thanks to everyone who has provided feedback so far and all the discussions here 16:22:02 #info help needed on some issues on that new docsite - https://github.com/ansible/jinja-docsite/issues 16:22:13 for those reading the minutes ;-) 16:22:28 Anything else you want use doing/looking at/thinking about? 16:22:57 not sure it belongs here but we could highlight the SSG topic 16:23:04 #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 go ahead Don Naro 16:24:32 #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 ...and vote closes today i think :-) 16:25:13 yeah I think so 16:25:43 website discussion - https://github.com/ansible-community/community-topics/issues/201 16:25:46 in case anyone wants to read up and then vote. 16:26:24 from a docs perspective, we'll be part of that new website over time. 16:27:14 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 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 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 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 I believe so, yeah. ssbarnea probably knows MkDocs the best. 16:34:05 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 ok cool. that was the only one that caught my eye because of what you just said lol 16:34:59 it also seems like MkDocs has some momentum behind it that Sphinx doesn't so I do like it for that 16:36:05 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 yeah that's a bennie 16:37:21 a bennie? 16:37:56 My WIP document on mkdocs can be visited at https://hackmd.io/@42/mkdocs-ansible 16:38:00 benefit... lazy typer 16:38:31 is not all green on the other side, but to me it looks much greener than sphinx 16:38:36 thanks ssbarnea ..I'll take a look after the meeting. looks good 16:38:39 does mkdocs also supports blogs? 16:39:12 (nikola and lector both support blogs) 16:39:32 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 do you know when soon will be? 16:40:21 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 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 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 you can start using the "insiders" features at any time if you are a sponsor. 16:43:04 i suspect that they will reach the next goal in less than 6mo 16:43:44 but we can also look at the other plugins too, is just that i did not had time 16:44:06 so if Ansible paid, we'd have blog support today? 16:44:14 i would prefer to use material because I know that is very well maintained and supported 16:44:21 yes, we can. 16:44:27 ok good to know 16:44:38 and my plan was to become official sponsor at some point 16:44:59 for now I am only sponsoring him personally 16:45:16 ok meanwhile in docs land... 16:45:28 #topic Open Floor 16:45:28 anything docs related we want to discuss? 16:45:30 🕺 16:45:38 open dance floor 16:45:41 hahah 16:46:13 hmm, do I understand it correctly that blog support for mkdocs is provided by a specific *mkdocs theme*? 16:46:18 #info vote on the forum topic - https://github.com/ansible-community/community-topics/discussions/211 16:46:33 the theme comes with its own plugins, blog being one of them. 16:46:55 but you could use/write another plugin to obtain similar functionality 16:47:12 think about material theme as bundle 16:47:26 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 yeah, you can mix and match, but not all play along well. i found some conflicts especially related to monorepo plugin 16:48:58 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 there are two other ones but i was not able to make them work for me, only that one looked ok. 16:49:39 ok, thanks! 16:49:45 This is a page/repo that should be watched, is updated every month 16:49:51 https://github.com/pawamoy/best-of-mkdocs 16:50:04 gives a good idea about trending up or down in mkdocs ecosystem 16:50:34 as expected, not all components are maintained so well 16:51:14 but I was glad that he theme was, especially as most Ansible contributors are not UX/HTML/CSS designers. 16:51:33 most of us are good at python, but not web stuff 16:51:46 the web stuff is dark magic 16:52:02 I was more inclined to say 'brownish' 16:52:13 lol 16:54:38 I need to take a quick break before the next meeting starts up. 16:54:51 thanks samccann 16:56:08 yep 16:56:13 #endmeeting