14:42:17 #startmeeting Documentation Supplemental Working Group Meeting 14:42:17 Meeting started Thu Nov 5 14:42:17 2020 UTC. 14:42:17 This meeting is logged and archived in a public location. 14:42:17 The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:42:17 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:42:17 The meeting name has been set to 'documentation_supplemental_working_group_meeting' 14:42:29 #chair acozine 14:42:29 Current chairs: acozine samccann 14:43:11 * acozine goes to retrieve some tea 14:43:14 felixfontein gundalow andersson007_ baptistemm you around? 14:43:20 o/ 14:43:23 kewl 14:43:43 #chair felixfontein 14:43:43 Current chairs: acozine felixfontein samccann 14:44:08 * acozine is back at keyboard 14:44:48 I'm going to try to state the problem, and see if we have a shared understanding of what we are trying to solve 14:44:56 #topic supporting independent release cycles for ansible-base and ansible in the docs 14:45:05 (mostly to be sure I understand it myself . . . ) 14:45:08 kewl 14:45:51 Now that collections and ansible-base (or future name TBD) are different repositories, they can be released on different timeframes. 14:45:58 * lmodemal in another meeting 14:46:55 The `ansible` PyPI package includes a specific version of ansible-base plus specific versions of selected collections. 14:47:40 In January we expect a release of ansible-base (or future name TBD). This will likely be 2.11. 14:48:21 We need to document its features separately from the `ansible` PyPI package . . . and this is where I get a little confused . . . 14:48:26 correction - it's Ansible that will be 2.11 14:48:35 ansible-base will still be 2.10 afaik 14:48:49 ahhh, okay 14:49:01 At least that's what I think is happening. Ansible 2.11 will releaes with ansible-base 2.10.x 14:49:02 so 14:49:22 we expect a release of the `ansible` PyPI package called 2.11 14:49:36 and some time AFTER that, we expect a release of ansible-base, ALSO 2.11 14:49:42 but a different 2.11 14:49:52 yep I think that's the problem statement 14:49:57 I agree 14:50:20 * acozine feels much more grounded now 14:50:45 #info problem statement - Ansible pypi package called 2.11 will release in jan/feb? and some time after that, ansible-base will release with a version called 2.11 (but a different 2.11) 14:51:24 will we, at some point, need to have documentation for multiple versions of ansible-base? 14:51:42 That's the big question for sure 14:51:47 #link https://etherpad.opendev.org/p/ansible-documentation-split 14:51:54 that's the scratchpad for ideas 14:52:23 Let's start with the question - who is/will use `ansible-base` without Ansible? 14:52:44 is it 99% developers only? 80% developers, 20% intrepid users? 14:53:29 I think over time the user percentage will increase 14:53:56 especially when people find out that they can just install what they need and it is faster and uses less storage 14:54:14 good point 14:54:16 but I don't have a working crystall ball :) 14:54:20 heh 14:54:46 Hi 14:54:47 #info we may see more community users installing just `ansible-base` and the selection of collections they are interested in. 14:54:54 #chair gundalow 14:54:54 Current chairs: acozine felixfontein gundalow samccann 14:55:46 so if we expect community adoption of ansible-base over time (for users), we should plan for a user section that is release-dependent 14:56:56 gundalow: do you have a sense of either 1) who will be using ansible-base, or 2) what would trigger an `ansible` 3.0 release? 14:57:20 is that ansible as in Ansible package, or a 3.0 `ansible-base` ? 14:57:29 or both/either :-) 14:57:32 Ansible package 14:57:57 for ansible-base, I think 3.0 would be a full-on rewrite of how the engine works internally 14:58:14 gotcha 14:58:34 that may be coming (or not), it's an ongoing discussion 14:58:50 while he's thinking deep thoughts... what is the significance to docs if Ansible goes to 3.0? 14:59:01 but would we ever have an `ansible` PyPI 3.0 based on an `ansible-base` in the 2.x range? 14:59:02 (other than documenting the big new thing) 14:59:40 short-term it would let us put them in a single drop-down, but I guess we shouldn't plan on that - eventually they must diverge 15:00:10 I'm just trying to get a sense of what version numbers we're likely to see in the next, say, two years 15:00:34 yeah I envision two separate (at least) docsites in that regard. docs.ansible.com/ansible and say docs.ansible.com/ansible-core or whatever the renaming is 15:00:59 I think ansible 3.0 would depend on ansible-base 2.1x.y, assuming ansible-base 3.0 isn't quicker ;) 15:01:13 then they have independent version numbers as needed, but could also support a release independent section... docs.ansible.com/ansible/developer (no version - just devel) 15:01:22 1) Customers will use `ansible-base`, and I expect somewhere between "some and lots" of others people will move to ansible-base 15:01:49 gundalow - will they? I got the feeling it was all wrapped up in execution environments when the time comes. 15:01:50 okay, so if we have separate docsites, I think we can solve this with a publication pipeline 15:02:12 `ansible-base==3.0` is a major version bump, so that would be when there is a big change in how things are done (ie backwards compatability breaking version change) 15:02:21 we already have version-specific documentation in the ansible/ansible repo 15:02:24 as in make webdocs vs make basedocs or something and then jenkins magic? 15:02:29 yeah 15:02:44 here's what I'm thinking, tell me which parts are crazy/won't work 15:03:08 we continue to document collections and ansible-base as we do now, in various repos 15:03:09 samccann: even if Execution Environments, isn't that still "users of `ansible-base` (and not `ansible`)" 15:03:58 we have one docstream that publishes from various branches of `ansible/ansible` to docs.ansible.com/ansible-core (or base or whatever it will be) 15:04:02 gundalow: my thought is that is entirely 'downstream' documentation.. so yea ansible-base is part of it, but it's likely to be documented as 'execution environment 1.x' and somewhere in the fineprint it will mention it's based on ansible-base 2.11 or something 15:04:53 we have another docstream that does what we do today: combines a specific branch of `ansible/ansible` with specific versions of collections to create docs.ansible.com/ansible 15:05:28 gundalow: what I'm leading toward is, there will be 'magic' (or possibly writers working frantically) to document execution environments for access.redhat.com. And they may borrow some of what we write for ansible-base upstream, but they aren't directly tied together 15:05:52 acozine: sounds reasonable. 15:06:02 Can you info those so we don't lose the idea? 15:06:28 gundalow: will execution environments exist 'upstream' in any sense that we have to document them for community users? 15:08:04 #info possible solution: one publication pipeline takes docs content in each maintained stable branch of `ansible/ansible` and publishes it as docs.ansible.com/ansible-core (or ansible-base . . . exact name TBD); a separate publication pipeline takes docs content from a specific maintained stable branch of `ansible/ansible` and combines it with specific versions of collections and publishes it as docs.ansible.com/ansible 15:09:03 should we switch the convo to what docs go in which buckets? or at least agree on the bucket types we are thinking about? 15:09:17 so in /ansible there will be the same things as in the corresponding /ansible-core, except that there are a lot more module/collection docs (and not just ansible.builtin), and maybe also things like scenario guides etc. that will be no longer part of ansible-core? 15:09:18 with a handydandy topic change to go with it 15:09:21 #info this solution would let us maintain a single source for documentation of core/base features that appears in versioned HTML for both the `ansible` PyPI package and `ansible-core` or ansible-base 15:09:46 felixfontein: yes, that's what I was thinking 15:10:04 write once, publish twice 15:10:11 hmmm 15:10:27 except they won't be "corresponding" versions for long 15:10:27 unsure about Execution Envionments existing upstream. I've not been following that as closely 15:10:34 (sorry in another meeting currently) 15:11:04 in other words, `ansible` 2.11 on PyPI will be based on `ansible-base` 2.10 . . . 15:11:06 Here's my worry - can we always assume Ansible will be running the most recent /ansible-core? 15:11:37 or will /ansible-core be documenting 2.11 before Ansible picks up 2.11 (much like happened with 2.10 15:11:38 samccann: I think we can, but even if it doesn't, I think this model will handle it 15:12:25 the hard part will be helping users understand the difference, figuring out which version of which package they have installed 15:12:34 /ansible-core will document 2.11 long before ansible picks up ansible-base 2.11 15:12:37 and from there, which version of which docsite they should be looking at 15:12:43 ok we can discuss offline on how the model chooses the correct version of the docs 15:12:45 ("long" being a couple of months) 15:13:06 yeah that's my worry. So in this model, it's all in ansible/ansible. 15:13:31 so other than freezing Ansible package documentation for those couple of months, how do we keep from publishing core 2.11 too soon? 15:13:36 we already define a long list of "for 2.x version of the `ansible` package, use this list of versions of these collections" 15:13:38 parts of the docs pipeline probably have to move out of ansible/ansible 15:13:45 we can add "and this version of ansible-base" 15:14:09 acozine - that's different. 15:14:20 We were distinguishing between this current version, and some older version 15:14:37 updates from Andrius/maxamillion: AFAIK the product team isn't scoping any upstream work on Execution Environments. Though the pieces (ansible-builder, CentOS/UBI8 container image) 15:14:40 felixfontein: hmmm, can we make the docs pipeline entirely its own thing? 15:14:46 what we are talking about now is distinquishing between this current Ansible version, and some FUTURE Ansible version that will pick up ansible-base 2.11 15:14:57 gundalow: thanks! 15:15:06 samccann: I'm not following you there 15:15:20 as of today the Community Team hasn't got it on the roadmap to build community Execution Environments (though maybe it could/should in the future) 15:15:33 acozine: I guess it depends on what is considered to be part of the docs pipeline 15:15:45 don't we currently say "pick this specific version of this collection" and download that exact version? regardless of whether there are older and/or newer versions availble? 15:16:10 acozine. I'm a user of Ansible 2.11, which includes ansible-base 2.10. I don't expect to read about future features that are coming in ansible-base 2.11, but that will show up in my docsite if Ansible just pulls in ansible-base docs. 15:16:41 the Ansible docs will pull in a specific version (specific stable branch) of the ansible-base docs 15:16:45 i'm not talking about collections. I'm talking about someone added a new ansible FEATURE... like I dunno, inventories in XML instead of INI or Yaml 15:16:55 yeah 15:17:06 Ansible docs are in the same branch. 15:17:25 if everything is in ansible/ansible github, then everything is tied to ansible-core branching 15:17:45 that's what felixfontein is saying - the docs pipeline will have to come out of that repo 15:18:33 so we could have a pipeline that said, "build the rst docs from `stable-2.10` and add these versions of these collections" 15:18:54 acozine: yes 15:19:19 having the pipeline outside of ansible/ansible makes it easier to implement that, since you don't have to backport every change to all possibly relevant branches :) 15:19:41 what is the pipeline in this discussion? 15:20:02 we could even jury-rig something that said, "kick off a job that clones the `stable-2.10` branch, build the docs, then add these versions of these collections and publish it as docs..ansible.com/ansible/2.11" 15:20:03 as in what pipeline exists in ansible/ansible today? I think that's my confusion. we called antsibull the docs pipeline for ages 15:20:52 heh, that's because our pipeline is more of a set of tunnels through different mountains (to stretch the metaphor) than a single pipeline 15:21:07 * samccann feels like we are solving the coding problem so to speak before we are solving what the information architecture will look like 15:21:14 with pipeline I mean everything that's not the docs themselves and that is used to build the docs, like theme, scripts to build config.rst, ... 15:21:22 samccann: good point 15:21:26 (I guess even the jenkins job description) 15:22:06 what do you think of the idea of having separate docsites for docs.ansible.com/ansible (for the PyPI package) and for docs.ansible.com/ansible-core/base/whatnot (for the standlone engine)? 15:22:11 samccann: ^^^ 15:22:22 is that good information architecture? 15:22:28 #info we may need to pull the docs publishing files out of ansible/ansible - such as theme, scripts to build config.rst, etc etc. 15:23:01 acozine - that's taking the cart before the horse so to speak. Again, solving the coding 15:23:42 What we need to figure out is - I'm an `ansible-base` user, what do I need for docs. Suzie is an `ansible-base` contributor (or developer, are they different people)? what does she need for docs 15:23:51 okay 15:23:57 ditto for Ansible the package, for Collection users vs developers etc 15:24:18 my point being - we are thinking of a two way split - it could end up being a 5-way split 15:24:25 I think (no idea whether that's right) that ansible-base users essentially need everything that doesn't document something that isn't part of ansible-base (i.e. some filters and scenario guides) 15:24:44 where users = developers, endusers, ... 15:25:15 #info ansible-base users/developers essentially need everything that doesn't document something that isn't part of ansible-base (i.e. some filters and scenario guides) 15:25:46 well, that's what I think :) doesn't mean it's true 15:26:24 heh yeah but i have the same thought... two thoughts = TRUTH! :-) 15:26:38 or at least worth saving in the meeting minutes 15:26:57 * abadger1999 is awake and reading the scrollback 15:28:22 ansible-base users need docs on the core features (how inventory works, playbook syntax, running locally, using roles, and so on) plus information on how to install and use collections 15:28:33 keeping that idea going - `ansible-base` users need to understand how to use collections as well. But does an `ansible-base` developer/contributor need the collection developer guide as well? I'm thinking yes 15:29:19 I've been thinking of this as - Ansible docs are nearly everything, and the subset is what `ansible-base` gets. 15:29:36 I think I would throw all developers/contributors into a single bucket, whether they contribute to `ansible-base` and/or to collections 15:30:17 But the flip way of thinking, is `ansible-base` users/developers need nearly everything, and as Felixfontein said, just not the scenario guides and some few other tidbits 15:30:40 samccann: ansible-base users are probably even more interested in creating their own collections than ansible users 15:31:06 at least the ones which aren't using it because RH told them "this is what we support" :) 15:31:15 acozine gundalow - my worry is - ansible-core runs their own show so to speak, can we guarantee their development model and requirements stay tied to what the collection development model is and will be? 15:31:31 https://github.com/ansible/ansible/pull/72476 <= jic someone wants to poke 15:32:24 though maybe that's not a valid worry, since individual collections (or groups of) set their own contributor requirements already 15:32:32 samccann can you give an example of them NOT doing that? 15:33:08 see above. Each collection can set their own contributor requirements. Though I'm sure there is some set of requirements that MUST happen. 15:33:49 But for example, core requires certain testing, which I think is moveing to azure? but a collection could use Github Actions or some such beastie instead. So the core testing requirements are different. 15:34:02 ah, so you're thinking of "how do we document 'How to contribute to Ansible' in a world where 'contributing to Ansible' can mean so many different things?"? 15:34:10 as in ansible-base/core has a set of developer guides... and collections has different developer guides 15:34:43 acozine yeah sort of. More like if I want to fix a bug in core, I'm doing something different than if I want to fix a bug in c.g 15:35:04 or aws.aws (if that even exists :-) 15:35:34 yeah, because each collection has its own guidelines, I think the best we can do for a collections developer guide is "generally this is how contributions work, consult the guidelines for the specific collection for more details" 15:35:41 we kinda already do that, right/ 15:36:10 we have a bit of a hodgpodge, but we may need to move to that model 15:36:44 I guess some things could be made clearer, but in general we have that I think 15:36:53 like 'ansible-maintained' collections have contributor/developer guidelines in our docs. aws has its own, though written by an ansible team member... etc etc 15:36:55 (related PR: https://github.com/ansible/ansible/pull/72494 :) ) 15:37:29 anyway I've lost the plot/topic we are covering 15:37:31 heh, `hacking_collections`, eh? 15:37:58 that's the label of that section :) 15:38:04 (in the collection dev guide) 15:38:12 yeah, it just made me laugh 15:39:05 samccann: let's see if a recap helps us pick up the thread 15:40:33 The Problem: soon there will be an `ansible` package version 2.11; some time after that there will be an `ansible-base/core/engine` version 2.11; current documentation cannot handle documenting any features that exist in `ansible-base/core/engine` 2.11 but NOT in `ansible` 2.11 15:41:05 yep 15:41:34 #info The Problem: soon there will be an `ansible` package version 2.11; some time after that there will be an `ansible-base/core/engine` version 2.11; current documentation cannot handle documenting any features that exist in `ansible-base/core/engine` 2.11 but NOT in `ansible` 2.11 15:41:34 The Opportunity: as we think about how to handle this situation, we can (and should) think about documentation personas - who will be using `ansible` package 2.11, and what do they need? Who will be using `ansible-base/core/engine` 2.11 and what do they need? 15:41:53 #info The Opportunity: as we think about how to handle this situation, we can (and should) think about documentation personas - who will be using `ansible` package 2.11, and what do they need? Who will be using `ansible-base/core/engine` 2.11 and what do they need? 15:42:12 now we come to Next Steps, where I am less certain . . . 15:42:16 we're over an hour and I've got a meeting in 16 min. Where do we go from here 15:42:55 so my thought on next steps - decide on 2-4 personas that we think will STICK. and take a stab at what each one needs to know (ignoring the current docs for now) 15:43:38 that sounds good 15:43:49 once we can write down and agree on 'what does a contributor vs user to ansible-base need' - say the top 5 tasks. then we can see if a two way split is good, or if we split more 15:44:06 samccann: +1 15:44:29 my other question - should we make thursdays the 'docssite split' meeting for a few weeks so we can make progress/decide? 15:45:03 Thursdays work for me . . . could we do it slightly later? 15:45:46 #agreed - next step - take a stab at 2-4 personas and the top 5 tasks we think they need in docs (ignoring current docs). That will help us know if we have a two-way split or more ways to split the current docs 15:46:00 I'm fine for Thurs as well. 15:46:02 #chair 15:46:02 Current chairs: acozine felixfontein gundalow samccann 15:46:13 #chair abadger1999 15:46:13 Current chairs: abadger1999 acozine felixfontein gundalow samccann 15:46:21 are you available at some better time on thursdays to continue this discussion? 15:46:53 +1 Thursdays 15:46:54 even half an hour later works better for me 15:47:01 +1 for later. 15:47:14 one later is fine for me 15:47:36 so 10:30am ET on Thursdays? 15:47:36 (I'm still in "maybe I'll be up, maybe I'll be asleep, maybe I'll be taking care of before-school kid problems" right now) 15:47:52 abadger1999: understood 15:47:57 samccann: that would be great 15:48:25 next week is better as all the planning meetings should be over 15:48:28 #agreed we will meet at 10:30am ET on Thursdays to discuss the docs split for a few weeks 15:48:38 thanks samccann! 15:48:39 oh the fun you have gundalow ! 15:48:50 anything else before we wrap up? 15:49:16 nothing from me 15:49:18 #info https://etherpad.opendev.org/p/ansible-documentation-split is the scratchpad of ideas. Please add your thoughts there as well between meetings 15:50:05 ok will end meeting unless someone pipes in real fast now 15:50:24 https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ?both 15:50:44 I wanted an excuse to play with hackmd.io, so I was going to flesh out personas based docs in ^ 15:51:01 nice! 15:51:03 oooo can I add that to the meeting minutes so we can stare at it later? 15:51:21 * acozine admires the colors 15:52:04 samccann: go for it - I think gundalow is still in double meetings 15:52:27 #info gundalows scratchpad for personas - https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ?both 15:52:30 ok ending now 15:52:36 #endmeeting