14:42:17 <samccann> #startmeeting Documentation Supplemental Working Group Meeting
14:42:17 <zodbot> Meeting started Thu Nov  5 14:42:17 2020 UTC.
14:42:17 <zodbot> This meeting is logged and archived in a public location.
14:42:17 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:42:17 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:42:17 <zodbot> The meeting name has been set to 'documentation_supplemental_working_group_meeting'
14:42:29 <samccann> #chair acozine
14:42:29 <zodbot> Current chairs: acozine samccann
14:43:11 * acozine goes to retrieve some tea
14:43:14 <samccann> felixfontein gundalow andersson007_ baptistemm you around?
14:43:20 <felixfontein> o/
14:43:23 <samccann> kewl
14:43:43 <samccann> #chair felixfontein
14:43:43 <zodbot> Current chairs: acozine felixfontein samccann
14:44:08 * acozine is back at keyboard
14:44:48 <acozine> 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 <samccann> #topic supporting independent release cycles for ansible-base and ansible in the docs
14:45:05 <acozine> (mostly to be sure I understand it myself . . . )
14:45:08 <samccann> kewl
14:45:51 <acozine> 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 <acozine> The `ansible` PyPI package includes a specific version of ansible-base plus specific versions of selected collections.
14:47:40 <acozine> In January we expect a release of ansible-base (or future name TBD). This will likely be 2.11.
14:48:21 <acozine> We need to document its features separately from the `ansible` PyPI package . . . and this is where I get a little confused . . .
14:48:26 <samccann> correction - it's Ansible that will be 2.11
14:48:35 <samccann> ansible-base will still be 2.10 afaik
14:48:49 <acozine> ahhh, okay
14:49:01 <samccann> At least that's what I think is happening. Ansible 2.11 will releaes with ansible-base 2.10.x
14:49:02 <acozine> so
14:49:22 <acozine> we expect a release of the `ansible` PyPI package called 2.11
14:49:36 <acozine> and some time AFTER that, we expect a release of ansible-base, ALSO 2.11
14:49:42 <acozine> but a different 2.11
14:49:52 <samccann> yep I think that's the problem statement
14:49:57 <felixfontein> I agree
14:50:20 * acozine feels much more grounded now
14:50:45 <samccann> #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 <acozine> will we, at some point, need to have documentation for multiple versions of ansible-base?
14:51:42 <samccann> That's the big question for sure
14:51:47 <samccann> #link https://etherpad.opendev.org/p/ansible-documentation-split
14:51:54 <samccann> that's the scratchpad for ideas
14:52:23 <samccann> Let's start with the question - who is/will use `ansible-base` without Ansible?
14:52:44 <samccann> is it 99% developers only?  80% developers, 20% intrepid users?
14:53:29 <felixfontein> I think over time the user percentage will increase
14:53:56 <felixfontein> especially when people find out that they can just install what they need and it is faster and uses less storage
14:54:14 <samccann> good point
14:54:16 <felixfontein> but I don't have a working crystall ball :)
14:54:20 <acozine> heh
14:54:46 <gundalow> Hi
14:54:47 <samccann> #info we may see more community users installing just `ansible-base` and the selection of collections they are interested in.
14:54:54 <acozine> #chair gundalow
14:54:54 <zodbot> Current chairs: acozine felixfontein gundalow samccann
14:55:46 <samccann> 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 <acozine> 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 <samccann> is that ansible as in Ansible package, or a 3.0 `ansible-base` ?
14:57:29 <samccann> or both/either :-)
14:57:32 <acozine> Ansible package
14:57:57 <acozine> for ansible-base, I think 3.0 would be a full-on rewrite of how the engine works internally
14:58:14 <samccann> gotcha
14:58:34 <acozine> that may be coming (or not), it's an ongoing discussion
14:58:50 <samccann> while he's thinking deep thoughts... what is the significance to docs if Ansible goes to 3.0?
14:59:01 <acozine> but would we ever have an `ansible` PyPI 3.0 based on an `ansible-base` in the 2.x range?
14:59:02 <samccann> (other than documenting the big new thing)
14:59:40 <acozine> 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 <acozine> 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 <samccann> 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 <felixfontein> I think ansible 3.0 would depend on ansible-base 2.1x.y, assuming ansible-base 3.0 isn't quicker ;)
15:01:13 <samccann> 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 <gundalow> 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 <samccann> gundalow - will they? I got the feeling it was all wrapped up in execution environments when the time comes.
15:01:50 <acozine> okay, so if we have separate docsites, I think we can solve this with a publication pipeline
15:02:12 <gundalow> `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 <acozine> we already have version-specific documentation in the ansible/ansible repo
15:02:24 <samccann> as in make webdocs vs make basedocs or something and then jenkins magic?
15:02:29 <acozine> yeah
15:02:44 <acozine> here's what I'm thinking, tell me which parts are crazy/won't work
15:03:08 <acozine> we continue to document collections and ansible-base as we do now, in various repos
15:03:09 <gundalow> samccann: even if Execution Environments, isn't that still "users of `ansible-base` (and not `ansible`)"
15:03:58 <acozine> 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 <samccann> 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 <acozine> 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 <samccann> 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 <samccann> acozine: sounds reasonable.
15:06:02 <samccann> Can you info those so we don't lose the idea?
15:06:28 <samccann> gundalow: will execution environments exist 'upstream' in any sense that we have to document them for community users?
15:08:04 <acozine> #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 <samccann> 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 <felixfontein> 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 <samccann> with a handydandy topic change to go with it
15:09:21 <acozine> #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 <acozine> felixfontein: yes, that's what I was thinking
15:10:04 <acozine> write once, publish twice
15:10:11 <samccann> hmmm
15:10:27 <acozine> except they won't be "corresponding" versions for long
15:10:27 <gundalow> unsure about Execution Envionments existing upstream. I've not been following that as closely
15:10:34 <gundalow> (sorry in another meeting currently)
15:11:04 <acozine> in other words, `ansible` 2.11 on PyPI will be based on `ansible-base` 2.10 . . .
15:11:06 <samccann> Here's my worry - can we always assume Ansible will be running the most recent /ansible-core?
15:11:37 <samccann> or will /ansible-core be documenting 2.11 before Ansible picks up 2.11 (much like happened with 2.10
15:11:38 <acozine> samccann: I think we can, but even if it doesn't, I think this model will handle it
15:12:25 <acozine> the hard part will be helping users understand the difference, figuring out which version of which package they have installed
15:12:34 <felixfontein> /ansible-core will document 2.11 long before ansible picks up ansible-base 2.11
15:12:37 <acozine> and from there, which version of which docsite they should be looking at
15:12:43 <samccann> ok we can discuss offline on how the model chooses the correct version of the docs
15:12:45 <felixfontein> ("long" being a couple of months)
15:13:06 <samccann> yeah that's my worry.  So in this model, it's all in ansible/ansible.
15:13:31 <samccann> 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 <acozine> 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 <felixfontein> parts of the docs pipeline probably have to move out of ansible/ansible
15:13:45 <acozine> we can add "and this version of ansible-base"
15:14:09 <samccann> acozine - that's different.
15:14:20 <samccann> We were distinguishing between this current version, and some older version
15:14:37 <gundalow> 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 <acozine> felixfontein: hmmm, can we make the docs pipeline entirely its own thing?
15:14:46 <samccann> 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 <samccann> gundalow: thanks!
15:15:06 <acozine> samccann: I'm not following you there
15:15:20 <gundalow> 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 <felixfontein> acozine: I guess it depends on what is considered to be part of the docs pipeline
15:15:45 <acozine> 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 <samccann> 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 <acozine> the Ansible docs will pull in a specific version (specific stable branch) of the ansible-base docs
15:16:45 <samccann> 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 <acozine> yeah
15:17:06 <samccann> Ansible docs are in the same branch.
15:17:25 <samccann> if everything is in ansible/ansible github, then everything is tied to ansible-core branching
15:17:45 <acozine> that's what felixfontein is saying - the docs pipeline will have to come out of that repo
15:18:33 <acozine> 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 <felixfontein> acozine: yes
15:19:19 <felixfontein> 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 <samccann> what is the pipeline in this discussion?
15:20:02 <acozine> 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 <samccann> 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 <acozine> 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 <felixfontein> 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 <acozine> samccann: good point
15:21:26 <felixfontein> (I guess even the jenkins job description)
15:22:06 <acozine> 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 <acozine> samccann: ^^^
15:22:22 <acozine> is that good information architecture?
15:22:28 <samccann> #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 <samccann> acozine - that's taking the cart before the horse so to speak. Again, solving the coding
15:23:42 <samccann> 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 <acozine> okay
15:23:57 <samccann> ditto for Ansible the package, for Collection users vs developers etc
15:24:18 <samccann> my point being - we are thinking of a two way split - it could end up being a 5-way split
15:24:25 <felixfontein> 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 <felixfontein> where users = developers, endusers, ...
15:25:15 <samccann> #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 <felixfontein> well, that's what I think :) doesn't mean it's true
15:26:24 <samccann> heh yeah but i have the same thought... two thoughts = TRUTH!  :-)
15:26:38 <samccann> or at least worth saving in the meeting minutes
15:26:57 * abadger1999 is awake and reading the scrollback
15:28:22 <acozine> 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 <samccann> 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 <samccann> I've been thinking of this as - Ansible docs are nearly everything, and the subset is what `ansible-base` gets.
15:29:36 <acozine> 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 <samccann> 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 <felixfontein> samccann: ansible-base users are probably even more interested in creating their own collections than ansible users
15:31:06 <felixfontein> at least the ones which aren't using it because RH told them "this is what we support" :)
15:31:15 <samccann> 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 <bcoca> https://github.com/ansible/ansible/pull/72476 <= jic someone wants to poke
15:32:24 <samccann> though maybe that's not a valid worry, since individual collections (or groups of) set their own contributor requirements already
15:32:32 <acozine> samccann can you give an example of them NOT doing that?
15:33:08 <samccann> 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 <samccann> 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 <acozine> 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 <samccann> as in ansible-base/core has a set of developer guides... and collections has different developer guides
15:34:43 <samccann> 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 <samccann> or aws.aws (if that even exists :-)
15:35:34 <acozine> 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 <acozine> we kinda already do that, right/
15:36:10 <samccann> we have a bit of a hodgpodge, but we may need to move to that model
15:36:44 <felixfontein> I guess some things could be made clearer, but in general we have that I think
15:36:53 <samccann> 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 <felixfontein> (related PR: https://github.com/ansible/ansible/pull/72494 :) )
15:37:29 <samccann> anyway I've lost the plot/topic we are covering
15:37:31 <acozine> heh, `hacking_collections`, eh?
15:37:58 <felixfontein> that's the label of that section :)
15:38:04 <felixfontein> (in the collection dev guide)
15:38:12 <acozine> yeah, it just made me laugh
15:39:05 <acozine> samccann: let's see if a recap helps us pick up the thread
15:40:33 <acozine> 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 <samccann> yep
15:41:34 <samccann> #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 <acozine> 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 <samccann> #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 <acozine> now we come to Next Steps, where I am less certain . . .
15:42:16 <samccann> we're over an hour and I've got a meeting in 16 min. Where do we go from here
15:42:55 <samccann> 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 <acozine> that sounds good
15:43:49 <samccann> 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 <abadger1999> samccann: +1
15:44:29 <samccann> my other question - should we make thursdays the 'docssite split' meeting for a few weeks so we can make progress/decide?
15:45:03 <acozine> Thursdays work for me . . . could we do it slightly later?
15:45:46 <samccann> #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 <samccann> I'm fine for Thurs as well.
15:46:02 <samccann> #chair
15:46:02 <zodbot> Current chairs: acozine felixfontein gundalow samccann
15:46:13 <acozine> #chair abadger1999
15:46:13 <zodbot> Current chairs: abadger1999 acozine felixfontein gundalow samccann
15:46:21 <samccann> are you available at some better time on thursdays to continue this discussion?
15:46:53 <lmodemal> +1 Thursdays
15:46:54 <acozine> even half an hour later works better for me
15:47:01 <abadger1999> +1 for later.
15:47:14 <felixfontein> one later is fine for me
15:47:36 <samccann> so 10:30am ET on Thursdays?
15:47:36 <abadger1999> (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 <acozine> abadger1999: understood
15:47:57 <acozine> samccann: that would be great
15:48:25 <gundalow> next week is better as all the planning meetings should be over
15:48:28 <samccann> #agreed we will meet at 10:30am ET on Thursdays to discuss the docs split for a few weeks
15:48:38 <acozine> thanks samccann!
15:48:39 <samccann> oh the fun you have gundalow !
15:48:50 <samccann> anything else before we wrap up?
15:49:16 <acozine> nothing from me
15:49:18 <samccann> #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 <samccann> ok will end meeting unless someone pipes in real fast now
15:50:24 <gundalow> https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ?both
15:50:44 <gundalow> I wanted an excuse to play with hackmd.io, so I was going to flesh out personas based docs in ^
15:51:01 <acozine> nice!
15:51:03 <samccann> 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 <acozine> samccann: go for it - I think gundalow is still in double meetings
15:52:27 <samccann> #info gundalows scratchpad for personas - https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ?both
15:52:30 <samccann> ok ending now
15:52:36 <samccann> #endmeeting