14:30:53 #startmeeting Documentation Working Group aka DaWGs 14:30:53 Meeting started Tue Nov 3 14:30:53 2020 UTC. 14:30:53 This meeting is logged and archived in a public location. 14:30:53 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:30:53 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:30:53 The meeting name has been set to 'documentation_working_group_aka_dawgs' 14:30:56 yay! 14:31:02 #topic opening chatter 14:31:08 * samccann waves 14:31:09 Hello o/ 14:31:20 #chair felixfontein samccann lmodemal 14:31:20 Current chairs: acozine felixfontein lmodemal samccann 14:31:24 who else is around? 14:31:26 omgosh doc n roll... that needs to be on a tshirt! 14:31:33 LOL true 14:31:43 any new folks here to chat about docs? 14:32:17 everybody's welcome and lurking (watching/reading but not typing/responding) is just fine! 14:32:55 * dericcrago waves 14:33:00 #chair dericcrago 14:33:00 Current chairs: acozine dericcrago felixfontein lmodemal samccann 14:33:05 dericcrago: welcome! 14:33:17 Hello dericcrago! 14:33:28 hi! 14:33:56 you're "furniture" now . . . being a chair means you get pinged a few times during the meeting, and if we have a poll we ask for your input 14:34:44 good ! 14:34:52 :) 14:35:43 agenda (posted again for the official minutes and in case anyone is just joining . . . ): https://github.com/ansible/community/issues/521#issuecomment-720513057 14:36:25 I wasn't sure what was covered last week so the agenda is a bit of a repeat 14:36:42 hi 14:36:59 I'm not sure what was covered last week, and i was here . . . it's the pandemic time tunnel 14:37:01 #chair aminvakil1 14:37:01 Current chairs: acozine aminvakil1 dericcrago felixfontein lmodemal samccann 14:37:05 aminvakil1: welcome! 14:37:32 acozine: thank you 14:37:51 aminvakil1: Welcome! 14:38:01 we'll start on official business, but for anyone joining late, just wave or say hi if you want to become a chair 14:38:34 #topic `latest` docs and downstream/upstream distinction 14:39:26 right now Ansible 2.10 is the `latest` release in our documentation, but it is upstream-only - there is no Red Hat-supported 2.10 release 14:39:54 so RH customers should be using 2.9 if they want RH support 14:40:15 the question is, can we make that obvious to folks who visit the docsite? 14:41:04 samccann: did you create a banner right before you went on vacation? 14:41:07 We have some of this up on test - see the banner at -http://docs.testing.ansible.com/ansible/2.9/plugins/become/runas.html 14:41:45 cool - so that tell people on 2.9 that there's a more recent community release 14:42:03 yep. I had latest up as well I thought but it's not there now. 14:42:07 do we have something for 2.10 telling people that it isn't RH-supported? 14:42:09 ahhhh 14:42:20 do you have the branch or PR handy? 14:42:25 this is the pr -https://github.com/ansible/ansible/pull/72269/files 14:42:28 awesome 14:42:36 * acozine kicks off a publication run to the testing site 14:42:48 it will say "You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this, or select any version in version selection to the left, including latest for the most recent community version." 14:42:54 for /latest/ aka 2.10 14:43:41 that looks like the text for 2.9 14:43:55 PR looks good 14:44:15 also good that the AnsibleFest banner gets deactivated :) 14:44:38 2.10 text is: `You are reading the latest community version of the Ansible documentation. Red Hat subscribers, select *2.9* in the version selection to the left for the most recent Red Hat release.' 14:45:01 Can't this be extended so that other users beside redhat also realize that their distribution ansible version may differ with the latest version? 14:45:08 felixfontein: the Fest banner is already gone: https://docs.ansible.com/ansible/latest/ 14:45:24 acozine: ah, even better :) 14:45:56 aminvakil1: what did you have in mind? 14:45:58 aminvakil1 - not sure what you are trying to clarify? 14:45:59 You are reading the latest community version of the Ansible documentation. Your ansible version may differ with this version. Red Hat subscribers, select *2.9* in the version selection to the left for the most recent Red Hat release. 14:46:05 something like this 14:46:10 aminvakil1: Not sure how relevant this is for other distros since you can only buy official support for Ansible at Red Hat. 14:46:13 #info https://github.com/ansible/ansible/pull/72269 14:46:19 tadeboro: welcome! 14:46:22 #chair tadeboro 14:46:22 Current chairs: acozine aminvakil1 dericcrago felixfontein lmodemal samccann tadeboro 14:47:11 aminvakil1: ah, so a general "just because you're reading the latest documentation doesn't mean you're actually using the latest version" clarification? 14:47:16 difference is this: Your ansible version may differ with this version. 14:47:36 acozine: yes, but tadeboro's point is good too. 14:47:36 People already had to select the right version based on what they have installed. But it is first time now that Red Hat-supported version is not latest stable. 14:48:25 so maybe this can be followed in another issue 14:49:17 And hi all o/ 14:49:25 in the past we always wanted everyone to upgrade to the latest version (not that people did . . . ) but now the latest version is further ahead of RH support, so more like the Fedora/RHEL situation 14:50:04 I think it is pretty common to point out in docs that you aren't looking at the latest officially released version, but I don't remember seeing a general banner "Make sure you selected the right version" everywhere 14:50:58 there is a banner for older versions as well - https://docs.ansible.com/ansible/2.8/index.html 14:51:00 and EOL 14:51:15 I sometimes wonder how many people actually read those banners . . . but I think it's good to have the information somewhere, so if a person is actively looking for "how do I know which version I should be looking at" they can find the answer 14:51:24 I think we have to assume people will verify their own version matches the version of the docs they are looking at. That's fairly common 14:51:31 oh, good 14:51:47 we might also consider an entry in the FAQ 14:52:06 "Which version of Ansible should I use?' 14:52:18 a faq entry for 'how to find what version of ansible you are running' is good. A faq for matching that to the docs version you are looking at is.... odd 14:52:39 Q: "why can't I find $(new feature) in the docs? why does $(new feature) described in the docs does not work for me?" A: "Check the version." 14:52:46 there's 4 possible scenarios, right? You're reading latest and that's also the Red Hat supported version, you're reading latest and that's not the Red Hat supported version, you're reading *NOT* latest and that's the Red Hat supported version, and you're reading *NOT* latest and that's *NOT* the Red Hat supported version 14:53:09 (meanwhile, the draft banner is up on http://docs.testing.ansible.com/ansible/latest/) 14:54:11 ok in all seriousness... I'm not seeing that technical people need to be told to find the right feature/version in the docs. That seems overkill 14:54:25 I first didn't see anything, and then I remembered I need to activate JavaScript for that :) 14:54:28 has anyone got an example of any docs... anywhere doing this? 14:55:00 samccann: heh, yeah, I was thinking more "how do I select a version, which is the right version to use?" with an answer like "if you want the latest features, use `latest`, if you are a RH subscriber, use `2.9` for Red Hat support" 14:55:49 dericcrago: right now of your 4 scenarios, users could run into 1, 3, and 4 14:56:02 1. reading `latest`, that's not the RH supported version 14:56:21 3. reading `2.9`, that is the RH supported version 14:56:25 do we have any evidence that this actually confuses enough users that it is worth adding an extra banner / extending the banner? 14:56:40 the 2.9 not being latest, yes 14:56:43 we're getting feedback from our support and sales folks that customers are confused 14:56:55 but not anything else that i've heard 14:57:12 I mean besides 2.9 vs. latest :) 14:57:14 i can recall from my experience telling my friends which use ubuntu, maybe i need to find some fedora users as friends:) 14:57:21 heh 14:57:31 acozine - understood, I was taking future states into consideration unless Red Hat support is always going to lag behind latest 14:57:54 ubuntu (lts) always has outdated software, I thought ubuntu users would know that they can never rely on documentation for latest 14:58:06 dericcrago: good point, I was hoping that could be a bridge we don't have to cross quite yet . . . 14:58:19 I vote for merging samccann's banner updates 14:58:25 republishing 14:58:30 +1 for merging 14:58:40 then waiting a while to see if we get more reports of confusion 14:58:41 +1 14:59:00 +1 :-) 14:59:15 +1 14:59:19 +1 15:00:14 #agreed merge banners, see if the problem of customer confusion on versions persists, if it does, try something else in future 15:00:47 #topic removing rst files from tarballs 15:00:51 I can confirm from my experience that people do tend to give me a strange look when I tell them that you cannot buy support for things in Ansible 2.10 from Red Hat if it is not part of a certified collection or Ansible 2.9 15:01:14 tadeboro: it's a confusing topic, for sure 15:01:30 though one look at the "all modules" list should help people understand 15:02:28 on topic: I like the idea of no longer having docs included in the default tarball, and instead have a docs tarball 15:02:36 https://github.com/ansible-collections/overview/discussions/120 15:02:45 felixfontein: that's a neat solution 15:02:55 I especially like the idea of having a .html tarball which contains the .html versions of the docs 15:03:54 for going forward with this (if this is what we want), I guess the best approach is first to create a docs-only tarball, and once that works (and there is a nice build/publish process for it), remove docs from the main release tarballs 15:05:13 felixfontein: iirc epel did exactly that 15:05:18 ansible-doc package 15:05:31 which is not related to the cli but to the html, they had to stop cause of sphinx issues 15:05:38 looking at comments on the issue above, there were two main concerns: 15:05:45 oh the sphinx joys... 15:05:52 1. the docs package might get stale 15:06:06 re 1: if it is auto-generated together with the main package, it won't get stale 15:06:19 felixfontein: not the pljgin content but guides/rest will 15:06:23 2. leaving out the rst files would mean `ansible-doc` wouldn't work 15:06:40 ansible-doc does NOT use rst, so leaving them out is fine 15:06:46 not sure where that got started .... 15:06:51 bcoca: but that's not because they are not included in the main tarball, but because nobody updates them in ansible/ansible 15:06:58 yep, neither concern is a blocker 15:06:59 guides will only be about a month old, right? since ansible has a dot release every 3 weeks or so? 15:07:12 we have ways to keep the docs package up to date 15:07:21 and `ansible-doc` works off the python files 15:07:30 yeah as part of the Ansible release build. so at most the docs are a month old 15:07:35 felixfontein: wrong, we do update in ansible/ansbile and the docsite MANY more times than we release, so they will be stale between releases vs teh docsite 15:07:56 bcoca: ah, if you consider that state, then yes 15:07:59 so the 'stale' concern is valid, but is minimized by frequ;ent releases 15:08:00 #chair bcoca 15:08:01 Current chairs: acozine aminvakil1 bcoca dericcrago felixfontein lmodemal samccann tadeboro 15:08:20 I assumed something else was meant by stale 15:08:24 and does not apply to plugin/module content for the most part 15:08:27 bcoca: I thought relrod was doing regular releases every 3 weeks? 15:08:38 acozine not afaik 15:08:41 3 weeks old doesn't seem that stale to me 15:08:41 I am personally fine with docs package being tied to the ansible package (aka once a month or every 3 week updates). 15:08:50 acozine: every four weeks 15:08:52 in a way, it's more accurate 15:08:52 i know it was asked for, but i dont believe we commited to it 15:09:09 acozine: schedule is 'release - 3 weeks - prerelease - 1 week - release - ...' 15:09:20 well, here is the thing, if you careate a docs package you are NOT boudn to core release schedule 15:09:28 that's also true 15:09:37 ansible is released every three weeks though 15:09:39 we can release the docs as part of the docsite publication if we want to 15:09:41 so ansible-html can have diff update cadence and ensure 'staleness' is even smaller 15:09:43 i'm not sure I follow that point bcoca 15:09:56 samccann: diff release cycles for 'code' vs 'docs' 15:10:14 acozine: updating the docs tarball during rebuilds is a bit problematic, since every new tarball needs a new version number 15:10:15 yes but then we get the alternate problem, docs talk about a feature that is NOT in the released ansible 15:10:17 you could, in theory', release ansible-html package every time you update docsite 15:10:25 so you'd end up with docs tarball 2.10.2.13 15:10:30 yeah that we cannot do 15:10:35 felixfontein: ah, I see 15:10:36 docs are updated for devel features all the time. 15:10:39 that would be a problem 15:10:43 samccann: then it would not be in the docs, afaik we keep those in doc versions per ansible version 15:10:54 well, it's doable, but it is unnecessarily complicated IMO :) 15:11:12 well, yes, its easier to 'live with small stale' and keep releases in sync 15:11:23 my nickel - we are complicating this. Tie the docs package to the Ansible package. 15:11:24 but having 2 packages, gives you the ability , JIC 15:11:28 btw, docs tarballs is related to the 'how should ansible-base and ansible docs be separated?' 15:11:55 felixfontein: not that I know of. It was only to shrink the size of the tarballs. 15:11:55 also collections update docs out of badn of core/base 15:12:10 * relrod sees he was pinged; reads up 15:12:11 samccann: there are the docs in ansible-base, and there are the docs in ansible 15:12:17 The idea of then creating an ansible-documentation tarball with HTML was a bennie 15:12:29 what is a "bennie"? 15:12:33 the only reason we shipped the rst was for downstream maintainers to build html, but since sphinx issues made that hard and afaik no one is using, just remove them imho 15:12:35 sorry... benefit 15:12:47 ok :) I guessed that, but I never heard the expression 15:12:55 and then note 'in future will have rst/html release pkg' 15:13:01 if you want 15:13:31 bcoca: removing .rst from ansible-base without having an ansible-base-docs package makes things more complicated for the build process though 15:13:32 samccann: i would not even restrict6 to html, have the rst there so people can build pdf/ascidocc/etc 15:13:51 so we had no way of knowing if ANYONE was using those rst files... that's were we started thinking let's make them available separately 15:13:56 felixfontein: if build depends on package, yes, if it depends on repo no 15:13:58 but we could just remove and wait for the screaming to start 15:14:02 heh 15:14:07 and if it doesn't? we are fine 15:14:16 samccann: hehe, yep 15:14:20 bcoca: if it's properly tied to the ansible build, it depends on the package 15:14:31 But we still have they often repeated 'why can't I have a pdf of the docs' issues. 15:14:34 how much work does this entail? a few hours of coding? or two weeks of dedicated work? 15:14:35 im +1 to have additional package, but i would not be one doing the work 15:15:03 if it's a few hours, I say let's give it a try, do a test run, and then have a debate based on the actual contents of the resulting packages 15:15:12 I'm also +1 to the additional package. Maybe we just need someone to give it a test run and see how easy/hard it is? 15:15:15 acozine: with previous build it would have been a short effort, i have no clue on current since i barely looked at it, toshio would have to asses that 15:16:00 okay, we can ask T. when it's actually morning where he is 15:16:01 felixfontein is more familiar and he seems to indicate it will require some non trivial changes 15:16:33 in the old we built direclty from repo so it was easy to just remove rst 15:16:38 it depends on whether ansible-base tarball includes docs or not 15:16:53 (and if not, whether there is an ansible-base-docs tarball coming with every ansible-base tarball) 15:16:54 felixfontein: if the point is to remove them from core tarball ... 15:17:32 that is probably a 1 day change, but would punt to @relrod for final answer 15:17:39 bcoca: I think the docs contained in the ansible tarball are a lot more than the ansible-base docs 15:17:40 I thought the point was to remove them from the `ansible` PyPI package, which is much much larger than `ansible-base` 15:17:57 I don't think 'space' was a real issue on the `ansible-base` tarball. So maybe we solve for Ansible package first and leave base alone (aka let the rst stay in base for now) 15:17:58 I'm still catching up, sorry 15:18:04 felixfontein: most of the rst are build from plugins, so that is not a factor the issue is the guides/faq/etc 15:18:06 relrod: no worries 15:18:21 this will not be fully decided today 15:18:23 relrod: how hard to separate rst files from core tarball and put in separate ansible-documentation package? 15:18:47 bcoca - with collections, there are a TON of rst files coming in now. Some collection owners are generating module .rst files on their own since Galaxy doesn't display module docs yet 15:19:01 samccann: but those still get generated same way 15:19:10 and are not included NOW in the core/base 15:19:22 my point is - they are all in the Ansible package now 15:19:40 bcoca: probably not that hard. This would be a separate .tar.gz on releases.a.c and package on pypi? 15:19:47 well, talking about 2 diff stages, 1st is to allow building ansisble + docsite from core 15:19:52 2nd stage you totally control 15:20:05 relrod: dont even think it requires pypi, just tarball 15:20:14 but not up2me 15:20:22 relrod: I don't think it matters much where the docs tarball ends up, as long as it is always the same place and the ansible build can rely on it :) 15:20:40 i disagree on your 1st stage bcoca 15:20:45 samccann: ? 15:20:48 The focus should be first on Ansible package 15:20:59 that is the size problem, last I heard, not 'ansible-base' aka core 15:21:06 samccann: but disucssing now how we get requirements for it 15:21:36 so ansiblebase can give you the 'part of rst' it supp;lied previouslly, that is what is being discussed with relrod, about the package you produce in the end, that is in toshio's lap 15:21:58 since core/base does NOT supply collection data, we can only be responsible for the data that is supplied now 15:22:10 why im making distinction on what each package will contain 15:22:32 it would be nice if a separate ansible-base-docs package already exists when someone starts working on stage 2 15:22:57 okay 15:23:04 sounds like we need a list of requirements 15:23:11 and that might require a bigger decision on what is 'purely core docs' and 'full ansible community docs' 15:23:13 Part of my issue is I'm not 100% sure how docs works now, I haven't done much with that part of the build pipeline since I took over. But I don't think it would be hard to split it out. 15:23:15 ah so `ansible-base` has the guide rsts, and Ansible the package has the collectin rsts today but NOT the guide rsts? 15:23:21 before anybody starts changing code 15:23:39 relrod: right now they seem to build from rst in our package + collections and generate both docssite and more rst for asnible package 15:23:53 relrod: I think one could simply remove the docs/ subdir from the current tarball, and put it into a separate tarball 15:24:01 samccann: no, ansible package is SUPERSET of ansible-base/core 15:24:20 felixfontein: yeah that's my thought as well, seems totally doable. 15:24:29 I'm happy to add some technical requirements to https://github.com/ansible-collections/overview/discussions/120 15:25:00 and we can revisit next week when we've got more of a roadmap 15:25:03 well, base/core side part is easy, the 'fun' part becomes deciding what does stay in core/base ... like vmware guide ... makes no sense there anymore 15:25:16 it sounds like everyone is on board with the general spirit of the change 15:25:42 make the tarballs more modular, give people the option to install the docs but don't force them to install them if they don't want to 15:26:10 well, they always get asnible-doc docs as they are embeded in the plugins 15:26:30 the option is the user/dev/other guides 15:26:40 bcoca: yes, that's great 15:26:46 * bcoca looks for sphinx info output 15:26:58 meanwhile we have four minutes left in the official meeting time 15:27:57 we don't have time today but we really must move forward on the ansible-base vs ansible docs split in the sense of 'what guides etc' will be on the website that focuses on ansible-base etc. 15:28:07 let's do a quick open floor 15:28:08 That has a ticking timebomb associated with it for ...Jan or Feb? 15:28:14 hmmm user guide manpage .... 15:28:31 but yeah open the floor 15:28:38 #topic open floor 15:29:09 https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output <= something we have gotten many requeests for, the general docsite in 'manpage' format 15:29:11 all questions, comments, requests for help, PRs for review, etc. now welcome! 15:30:10 I have opened an issue for the previous discussion about users with not up-to-date ansible versions using docs in https://github.com/ansible/ansible/issues/72459. 15:30:21 cool thanks! 15:30:55 ;) 15:30:55 aminvakil1: sounds great, thanks for capturing that conversation so we can follow up 15:32:22 no other open floor topics? 15:32:42 not from me 15:32:49 i have one quick one - should we have a separate meeting to discuss how to split out ansible-base on the website? 15:32:57 I'm still happy for reviews of https://github.com/ansible/ansible/pull/72335 and https://github.com/ansible/ansible/pull/72354 :) 15:33:04 a quick reminder that everyone is welcome to add topics to the official agenda 15:33:17 just add a comment to https://github.com/ansible/community/issues/521 15:34:20 #info reviews encouraged on https://github.com/ansible/ansible/pull/72335 15:34:40 #info and also on https://github.com/ansible/ansible/pull/72354 15:35:26 samccann: how about a meeting on Thursday? 15:35:59 I think in the short term, the ansible-base docs will be like the `devel` docs 15:36:14 we can publish the new version, with no collection docs attached 15:36:22 Thur sound good to me 15:36:24 that will work until the version numbers start overlapping 15:36:41 with ansible-base docs, do you mean what would end up on docs.ansible.com/ansible-base/? 15:37:03 felixfontein: we're not sure 15:37:04 something like that yes felixfontein... for when Ansible 2.11 releases but includes ansible-base 2.10 15:37:29 so does this same time work for folks on Thursday to go in depth? 15:37:31 right now we have an ordered set of versions 15:37:38 that may not always be the case 15:37:54 samccann: works for me 15:38:15 I'm in 15:38:18 not sure whether I'll have time, but I'll try 15:38:19 anybody else free on Thursday at the usual DaWGs meeting time? 15:38:52 felixfontein: it would be great to have you there if you can make it 15:39:32 I'll try! 15:39:59 it would be great to have loads of people there - this change will affect everyone, so get your opinions heard! 15:40:28 okay, I'm going to close the official meeting, then go feed m ycat 15:40:34 heh 15:40:37 she doesn't understand about the time change 15:40:57 #agreed we will meet on Thurs at 9:30ET to discuss splitting the docsite up 15:40:59 hehe :) 15:41:14 thanks aminvakil1 bcoca dericcrago felixfontein lmodemal samccann tadeboro 15:41:21 our cats think it's feeding time all the time, so they don't actually need to care about time change... 15:41:36 FYI, ansible-base is being renamed, possibly to ansible-core so i would wait to finalize names till then 15:41:46 good to know, thanks 15:41:58 thanks bcoca 15:41:59 bcoca: is there a schedule attached to that rename? 15:42:01 our cats think it's feeding time all the time, but if we let them eat all the time they'd be enormous, they're big enough already 15:42:04 felixfontein: i wish 15:42:17 #endmeeting