08:14:55 <maxandersen> #startmeeting
08:15:04 <jbott> Meeting started Thu Feb 24 08:14:55 2011 UTC.  The chair is maxandersen. Information about MeetBot at http://wiki.debian.org/MeetBot.
08:15:04 <jbott> Useful Commands: #action #agreed #help #info #idea #link #topic.
08:15:04 <maxandersen> i hope so ;)
08:15:19 <maxandersen> #topic Community vs Product docs
08:15:36 <maxandersen> so just got one question come up yesterday from SE's complaining our docs looks like they are written for community and not product.
08:15:57 <maxandersen> that is probably/most likely true  since there is no separate phase for doing productization.
08:16:31 <mcasperson1> the only difference I was made aware of was that the JBDS docs don't get things like the deltaclouds manual
08:16:40 <maxandersen> but at least we should minimize the confusion where we can - i.e. we should not in every reference refer to jboss.org/tools updatesite and download if we do that still.
08:17:00 <mcasperson1> that was something I wanted to ask you...
08:17:23 <mcasperson1> a lot of the docs for the individual components have their own installation instructions
08:17:57 <maxandersen> yeah and I realize my previous requests for please removing that to exadel docs didnt work.
08:18:10 <maxandersen> something we need to get out IMO.
08:18:17 <mcasperson1> I was wondering if there was any need for individual installation instructions, or if we should just have one set of instructions for installing all the tools (either from jboss.org of with JBDS)
08:18:23 <maxandersen> yes exactly
08:19:14 <maxandersen> with only 1-2 guys working on this massive doc set we need to be rational about what actually goes into these.
08:19:58 <mcasperson1> ok, so in something like the getting started guide we have instructions for adding a JBoss.org update site in Eclipse and installing the plugins, instructions on how to install JBDS, and how to update both, and just reference those instructions from the other docs?
08:20:19 <maxandersen> i.e if the docs could just point to a relative location, i.e. ../../installation and then we have that be specific for JBDS or for JBoss Tools ?
08:20:38 <maxandersen> or a specific url that is specified at build time.
08:21:15 <maxandersen> #idea have our doc builds have a product/community specific installation link which can then have different content based on the context.
08:21:53 <mcasperson1> I guess we could have a common DocBook chapter that is included in multiple docs. Would you want to see the same instructions in each book (a common XML file on our end that gets compiled into each), or a single location that is linked to?
08:24:54 <maxandersen> mcasperson1: I would prefer a separate single location to not run into the same problem of having pages of duplicate info in these like for typographical conventions.
08:26:21 <mcasperson1> ok. i don't know how a stable url would work. from what I can tell, we just upload new versions of the docs for each version of JBDS. There is nothing like http://docs.redhat.com/JBDS/latest/gettingstartedguide.html#install
08:26:41 <mcasperson1> but i guess that just means we keep the links updated as we push out new released
08:27:11 <maxandersen> mcasperson1: maybe
08:27:28 <maxandersen> at least something to look at for next rev.
08:27:44 <mcasperson1> well, doing it manually for now is not a big deal
08:27:59 <maxandersen> #action mcasperson1 review docs for jboss.org tools specific installation instructions and extract/refactor to be usable from both product / community perspective.
08:28:45 <mcasperson1> we do have the ability to do conditional builds on the docs. i'll keep that in mind as we go through with the next revision with an eye to keeping product/community seperate
08:29:19 <maxandersen> relative links would be great here ;)
08:29:25 <maxandersen> no need to update them everytime...
08:29:32 <mcasperson1> thats true
08:29:43 <maxandersen> but hard to support for pdf's
08:31:00 <mcasperson1> i'll look into it. we might be able to define a base url as an entity and use that as a kind of global variable
08:31:32 <mcasperson1> maxandersen: so I guess the biggest thing I need from you is an idea on what is actually happening for the next release
08:32:15 <mcasperson1> i need to get a plan done of what new features need to be documented, what didn't work in the docs from your end, things like that
08:33:19 <maxandersen> yes - for JBDS 4.1 its basically nothing new
08:33:41 <maxandersen> just bugfixes and move of BPEL from techpreview to supported.
08:34:20 <mcasperson1> the kind of bug fixes that need full documentation, or just release notes?
08:35:11 <maxandersen> mcasperson1: the bugfixes aren't declared yet - the BPEL stuff might need more docs - but we'll need to get the BPEL team to drive input for that.
08:35:33 <maxandersen> #action maxandersen provide input for doc team for next release JBDS 4.1
08:35:57 <mcasperson1> what is the release date for 4.1?
08:36:35 <maxandersen> June/July - still moving target.
08:37:05 <maxandersen> its mostly a SOA thing so i'm trying to find someone on their side to drive it.
08:38:02 <mcasperson1> So from your point of view the changes to the docs will be limited to probably release notes for the bug fixes, and whatever the BPEL team can tell me that they are doing?
08:38:17 <mcasperson1> and the 1 or two JIRAs that were outstanding from the last release?
08:42:06 <maxandersen> mcasperson1: it will be more than 1 or 2 bugfixes - the 3.2.x bucket is pretty big by now. it wont be all in there though. But i've asked all devs (hoping they get it ;) that thay make sure its only bugfixes and jiras get clearly marked with what changes were done/needed if any for user.
08:43:12 <mcasperson1> maxandersen: so the docs will reflect any bugfixes that might change how the users interact with the software?
08:43:25 <maxandersen> yes
08:43:50 <mcasperson1> and these will be clearly described and tagged as such in the JIRAs?
08:43:55 <maxandersen> thus if not many doc changes in that period it would be good to do some of this product cleanup stuff?
08:44:18 <maxandersen> mcasperson1: yes - that is my intent. Probably need your help to see that happen.
08:44:39 <maxandersen> mcasperson1: i.e. raise issues again if not documentedenough for you to use/understand.
08:46:04 <mcasperson1> maxandersen: yeah. this time around I'll be issuing Docs Jiras against incomplete or poorly documented Dev Jiras. The Devs seem to respond to a JIRA more than an email.
08:48:05 <maxandersen> mcasperson1: yes exactly - plus jiras are much easier to share, monitor and reassign/blame on ;)
08:49:04 <mcasperson1> maxandersen: So until I start seeing some JIRAs from the devs about bug fixes they deem noteworthy and the BPEL guys give us some info, the priority is to clean up the docs and provide a clean separation between product and community releases? Also, what tag will these JIRAs have (so I can keep an eye on them? Will it be the new_and_noteworthy tag?
08:49:48 <maxandersen> mcasperson1: for now the amount of issues should be limited so fix for 3.2.1 is the simplest approach.
08:50:51 <mcasperson1> So i just keep an eye on any JIRAs resolved for 3.2.1, and the ones that impact the users will be noted as such?
08:52:15 <maxandersen> mcasperson1: yes - I will stress that to the team.
08:53:04 <mcasperson1> maxandersen: would it be easier to just reuse the new_and_noteworthy tag? that seemed to work well for keeping track of these kinds of bugs last time.
08:53:54 <mcasperson1> that way I can just filter on resolved for 3.2.1 and new_and_noteworthy
08:55:36 <maxandersen> mcasperson1: yes probably. though any .z release shuoldn't really have that many new and noteworthy ;) but yes - works for me.
08:56:43 <mcasperson1> maxandersen: it would also be handy if we could tag "known issues" JIRAs too (last time it was just my best guess as to what went in the release notes)
08:56:59 <mcasperson1> although i guess that wouldn't happen until just before the release
08:57:13 <maxandersen> yes, that should be marked by setting "affected version"
08:58:03 <mcasperson1> maxandersen: so how does that work? would I filter for open JIRAs that affect 3.2.1?
08:58:41 <maxandersen> 3.2.0.GA/3.2.1 affect.
09:01:24 <mcasperson1> maxandersen: I'm not sure I get it. so the known issues would be any JIRA that affects 3.2.1 that is still open at the time of release? or would I be looking at JIRAs that affect 3.2.2 just before 3.2.1 is released?
09:03:17 <maxandersen> mcasperson1: known issues would be those marked as Affects 3.2.0.GA/3.2.1
09:03:23 <maxandersen> and still open yes
09:03:46 <maxandersen> affect 3.2.2 is "broken" in the sense that it wont exist yet at that time ;)
09:04:32 <mcasperson1> maxandersen: ok. who are the BPEL guys? Do I need to get in contact with them directly about material for the docs, or will they contact me?
09:05:49 <maxandersen> mcasperson1: the BPEL guy(s) are Bob Brodt and to some extent Brian Fitzpatrick.
09:06:08 <maxandersen> once JBDS 4.1 is a bit more defined I'll make sure they are on this.
09:08:50 <mcasperson1> maxandersen: great. so it sounds like there isn't a whole lot that needs to be done on the docs side of things for 4.1/3.2.1? Is there anyone else (except for the BPEL devs) who would have anything they needed from us that I should talk to?
09:11:35 <maxandersen> mcasperson1: right now I cant think of one; but now that we  have JBDS 4 GA we are finally getting the feedback we looked for the last year - so there might be more coming in.
09:12:03 <mcasperson1> maxandersen: i'll keep my ear to the ground then
09:12:08 <maxandersen> i.e. I was notified about the install diffs/overlap by an SE trying out JBDS 4 GA.
09:12:16 <maxandersen> yeah probably the best ;)
09:12:48 <maxandersen> so I would say JBDS 4.1 would be a good deadline to have for cleaning up/aligning docs for community/product split.
09:13:15 <mcasperson1> maxandersen: I can definitely do that. So is there anything else you want to bring up?
09:13:29 <maxandersen> nope - not at this moment.
09:13:34 <maxandersen> end meeting?
09:13:40 <mcasperson1> sweet. sounds good to me
09:13:44 <maxandersen> #endmeeting