14 January 2014
6. New item: DITA 1.3 proposal process: Lessons learned
What worked well?
What didn't work?
How can we improve the process in the future?
Kris: it's time to look at this; what can we do? what did we learn?
Eliot; I think it worked remarkably well; having the new requirements on the different stages of the proposals really made work more efficient.
Joann; Stan led a discussion about this at last week's TechComm SC mtg.; we noticed that there ended up being a multistage process for SC deliverables. We'd propose a stage in there for SC proposals coming in, to have another review stage; for someone in TC to look over proposals from a technical point of view. So we could use an extra review or support from experienced TC members to SC members writing proposals for the first time.
Kris; We tried to support that, but we needed proposals to be authored by involved parties.
Robert; We either need an extra step, or have a req that there be a tech review before it comes up for discussion, at both stage 2 and 3. Generally speaking, as the first person to integrate both 1.2 and 1.3, it was much easier to integrate; as a proposer, it was much harder, but well worth it.
Scott; It seemed like the deliverable templates were different between stages; I think it would be better if they were more consistent so you weren't having to rewrite and reformat things.
Kris; It would be good to reduce rework, but different stage templates are asking for different kinds of things. We don't want something that can have 'TBD' or 'n/a' in them, as we would get if the Stage 2 & 3 templates were more consistent.
Kris; we'll continue this next week.
21 January 2014
3. DITA 1.3 proposal process: Lessons learned
What worked well?
What didn't work?
How can we improve the process in the future?
Nancy brought TC up-to-date on last week's discussion;
- BobT; I think current framework is adequate; maybe we could have more consideration of requirements for each stage.
- Kris; can you suggest things reviewers should be
- BobT; wrt incompatibilities of architecture that would require major changes to proposal; the sooner we can discover those, the better. In an SC, you have 2 levels of review for every change; things have to be voted on by SC, then reviewed and approved by TC.
- Don; Bob, were you affected by TC's decision to add structural 'div'?
- BobT; no, we weren't
- Don; as I remember, it affected some proposals
- BobT; But I don't want a more cumbersome process
- Robert; Do you want to avoid more additional steps?
- BobT; yes,
- Kris; maybe we don't need extra steps for stages, but at some point we could have an official TC tech reviewer for each SC-sourced proposal.
- Robert; and this should take place before you even take the proposal to the SC for approval. so time isn't wasted later.
- Kris; yes, as soon as an SC proposal passes stage 1, it needs a 'technical advisor.'
Kris went over some things that affected her:
- overhead with 3-stage process
- it got cumbersome when folks did multiple updates to KAVI
- maybe we could have done better if we started out using trello...
- next time, should we have DITA proposal source stored in SVN rather than KAVI?
- Nancy; so when do we move it to KAVI
- Kris; We would store DITA source in SVN, and store the rendered source (HTML & PDF) in KAVI.
- Robert; from a source control standpoint, that would be better. Another thing is that we switched from wiki to trello halfway through, and that complicated things
- Kris; The only cost in storing source in SVN would be a possible learning curve for anyone not used to SVN.
- Kris; any other thoughts about proposal process?
- Deb; It was a little disappointing to start off with over 100+ proposals and end up with only 36...
- Robert; i think that was good; it means only the most important proposals go through; we got a more focused release. I think it's better not to encourage folks to include everything, because then some things get rushed in at the lat minute without enough review.
- Nancy; Also, a number of proposals were addressed as code or doc fixes
- Kris; And some were dropped because they came out of MI SC and had no one to do the work; others were just not technically feasible.
- Robert; some had alternate solutions that already were doable, and dropped out for that reason.
- Kris; looking at 1.3, I think there's a lot in there.
- Joann; but some things 'disappeared'...
- Robert; some items from 1.2 didn't have people to push them; the proposers had dropped off the committee and couldn't work on them, so expertise wasn't there to work on them.
- Joann; we should drop things explicitly
- Kris; we did do that
- Robert; there was nothing that was quietly dropped; we left things in the wikis for months waiting for someone to pick them up; if something was dropped, it was at a TC meeting and was recorded.
- Michael; We also need to consider speed and complexity; a number of items dropped off in order to allow us to make our schedule and to keep the release managable in terms of complexity. We were very concious of the tradeoff between adding features and not letting DITA get too complex. The number of proposals had to balance that rate of change.
- Kris; thanks, Michael, very good point; that was very much a guiding principle.
- Robert; as a primary editor on both 1.2 and 1.3, editing worked so much better on 1.3 because of the new process.
18 March 2014
3. New item: DITA 1.3 review process: Lessons learned
- What worked well?
Eliot; I thought it went really well. Thanks to Kris for setting up the DITAWeb tool with revisions organized by proposal.
[general agreement that Kris's preparations had lot to do with review success.
BobT; can't really see it getting much simpler than that.
Robert; this was more successful than any review ever done in DITA 1.2.
Eliot; the way we did the 3-stage preliminary reviews made it work much better; we didn't have to completely reword proposals for this review, so we could focus on small but important items.
Kris; ease was also driven by the fact that we used a subjectscheme to organize the revision values, and DITAWeb built a widget to enable using that easily. kudos to Mekon!
- What didn't work well work?
???
- Are there things that we need to improve?
???
28 October 2014
11. On-going items: DITA 1.3
Lessons learned re proposal and review processes
What worked well?
What didn't work?
How can we improve the process in the future?
Normative terminology
Eliot; for next week, I posted a message about markup//terminology; can we discuss that next week?
Kris; Robert and I will have to think about that in our review; the question is; do we have the time to discuss and come to agreement on terminology, especially when the conflicts already exist at 1.1, 1.2.
Eliot; I think it's important; for example, the term 'navigation tree' may not be the right term for what we've used it for.
Robert; I also noticed a review comment where Eliot made a formal objection to something we'd already decided on, in this case an undocumented @collection-type value of 'tree' in the topic module, for the linklist/linkpool elements. This came up at the 14Jan2014 TC meeting; we discussed it and decided to leave it in the DTD and mark it as deprecated, and leave it out of the XSD schemas; the TC approved this.
Eliot; I don't remember the meeting when it was voted on.
Robert; a further concern; the TC had made that decision based on precedent, in 1.1, we noticed that 'object' in the DTD, but not XSD, included a @longdescre; we added @longdescref but left the error in for backwards compatibility. Eliot's RNG is making changes to XSDs that change out past decisions.
Eliot; I'll make changes on tree value on links and longdescre @.
Kris; there's also a Trello card on tree value on links
ActionItem: Eliot will update RNG and transforms to implement the TC's decisions on maintaining backwards compatibility wrt @longdescre in 'object' and @collection-type="tree" in linklist/linkpool within base topic module. see https://trello.com/c/JM3CYsFR/12-fix-bug-in-definition-of-collection-type-in-dtd
and https://lists.oasis-open.org/archives/dita/201401/msg00037.html for more detail.
Tuesday, 2 June 2015
13. On-going items: DITA 1.3
Lessons learned re proposal and review processes
What worked well?
What didn't work?
How can we improve the process in the future?
Normative terminology
Stan; if 2.0 is radically different from 1.3, how relevant to it are 1.3 issues? It's a gap; we have no clue on what 2.0 will be, I feel a little wierd going into approval process with no idea of what's coming next.
Robert; that's the same as always; I have some thoughts about 2.0 floating in my head, more about process than content. most of changes will be driven by what's happened in 1.x.
Eliot; also a question of how big a break should 2.0 break; ground up re-do, or just changes that aren't backward compatible.
Kris; we need to break back-compat. fixing bad design choices, or to fix long-standing problems, but we don't want to break things for sake of breaking things. Let's mimimize pain in migrating
Don; backwards-compatibility statment is in part a statement that we will continue to provide continuity for the DITA community. We have things to fix; the solutions should enable community to continue doing business as usual, but better.
Kris; there will be breakage, so folks will have to do some work, but 2.0 will provide support to do that. Stan, does that answer your question?
Stan; looking at the barriers to adoption, etc, the sooner we can engage with that, the sooner we can start to work on those.
Kris; I think we should limit the number of features that any one individual can own?
Robert; I think that means prioritizing what you want to do and only doing the important ones.
Tom; it also means getting others to help more.
Don; if you have a suite of items, spread the work out.
Eliot; my preference would be to do nothing for 5 years, and let 1.3 age and mellow.
Don; yes, but we'll see changes in the way communities develop and publish info.
and need to project the directions content is going, so this is how we'll need to support the community, and also enable growth of the community.
Kris; in view of the fact it took 5 yrs to get to 1.3, we can't just wait 5 yrs...
Robert; even if we started work this summer, it will take us years to get there.
Kris; we also have other things on the horizon, Lightweight DITA and perhaps a pharma profile.
Eliot; the same people who would contribute to 2.0 are currently busy with 1.3, so I don't want to start on 2.0 too quickly; I don't want to be pressured to ocme with proposals in the short term.
Robert; that won't happen. I have a lot of proposals for 2.0 in my mind already; most of them involve stripping things out.
Tom; if we put a limit on features one person could own, we could lose important changes. so we just have to prioritize; we don't want an arbitrary limit
Eliot; we did that in 1.3
Robert; but in a number of places, you had too much stuff on your plate, and the process slowed down.
Kris; I will remain a really stauch advocate of limiting individual proposals, will also spread the wealth around
Robert; it's a bad sign when we have lots of things we consider high priority, but only one person to do them.
Don; by that time, the demographics of the group will be different
Kris; yes; how do we ihnsure long-term health of voting membership of TC? we don't want to lose the 'gene pool' of ideas.
Kris; and we want to make sure we have a steady supply of people who make those ideas into the reality of the spec. chairs, spec editors, sec'ys.
Stan; when we went thru 1.2 approval process, we contacted lots of OASIS mmvbers, for 1.3 we should piggyback on that with recruiting.
1 September 2015
8. On-going items: DITA 1.3
Lessons learned:
What worked well?
What didn't work?
How can we improve the process in the future?
Kris; anyone want to contribute to this?
Don; the proposal template updates improved ability of TC to review proposals.
Eliot; agree, that process worked well; forced writers to have proposals much more complete and well-formed.
Robert; it made editorial changes much easier.
Stan; I agree; I think this release ran about as smoothly as possible.
Chris; agree; I wonder if, when we get to stage 3 process where actual spec language goes into the spec, it would be better if the actual proposer had to incorporate actual spec language into spec?
Eliot; where various proposals made many small changes to a single piece, that could be more confusing.
Kris; as editor, I'd say it would be very good if we could improve review of proposals before they came to the TC for formal review.
Robert; they were better than in 1.2, but not perfect. Having language written up was the single best difference, it forced proposal writers to think much harder about providing complete and accurate info. In 1.2, we got to spec integration with big holes.
Kris; e.g. intersection of key scopes and subjectschemes...
Eliot; in SGML and HyTime, we would meet face-to-face 3 times a year for day(s)-long review. TC doesn't have that option.
Kris; do we want to try to consider having more face-to-face TC meetings?