The specification development process

Hello,

In issue #536[1], Dimitre comments on our process. I’m moving this
discussion to email because I don’t think it’s relevant to the question
of operator symbols raised in #536 and I doubt it will be constructive
to discuss it in a series of comments on an issue anyway.

I’m taking my chairing hat off here. What follows are my personal
observations.

> Isn't it good to have an agile approach to this project, with goals
> that are established, agreed upon and understood by everyone, with
> clear starting documentation and supporting tools, with probably
> bi-weekly or monthly Sprints with tasks commitments as part of every
> Sprint?

I am very, very skeptical that adding more process to the process will
make the process run more smoothly. Working backwards through the
preceding paragraph:

1. Commitments are a great idea. But we are all volunteers. Editing QT4
specifications is not my full time job. I might carve out three hours
for spec work this week, then ten next week, then none for two weeks.
The only *practical* commitment I can make is that I’ll do as much work
on QT4 as I can. I wouldn’t be surprised if many of us are in the same
position: doing spec work in between product development and supporting
our customers.

2. I don’t know what you mean by “clear starting documentation and
supporting tools.” We author in XML with a vocabulary that has a schema:
that’s one definition of clarity, I guess, and for supporting tools, you
can use any XML editor you like. If you think we could make better
progress by authoring in, for example, Markdown, start by demonstrating
that it would even be possible to maintain the richness of markup that
we need for our established processes.

We are not spinning up a new project: we are extending a project that
has a twenty+ year history. Is some of that history baggage that we
probably wouldn’t pick up now if we weren’t already carrying it? Yes,
probably. But (a) we’d just pick up other baggage and (b) it would be
difficult to put down now.

Any radical change in our specification authoring/build process, even if
you could get the entire group to agree to precisely the same thing
today, would delay all progress by six months at a minimum, perhaps a
year or more. I don’t believe our enthusiasm for the project would
survive that delay nor that our users would thank us for it.

3. The whole *point* of a working group is to establish goals that are
agreed upon and understood by everyone. That’s *why* we have issues,
pull requests, mailing lists, working drafts, and weekly meetings.

One painful aspect of the process is that there are some issues on which
*we will not agree*. That’s just the way it is. Committees by their
nature don’t produce (can’t produce!) the best possible design as seen
by the vision of one person. They produce the best possible design they
can as a group comprised of the individuals who turn up and do the work.
They accept proposals for alternate visions, engage in debate about
those visions, attempt to persuade other members that their alternatives
are superior, and eventually compromise. I might believe that
alternative “A” is better, but if everyone else has decided that “B” is
a better alternative, sometimes I just have to take my “I told you so”
token, save it for another day, and accept “B”.

I won’t be helping the process by being intransigent to compromise or
insisting on reopening the issue at every opportunity in the hopes that
“A” will suddenly have become the preferred answer.

> We might only need about a week to establish such a process and the
> needed starting conditions, and soon after that people will notice how
> much more straightforward our efforts will be.

Can you articulate a concrete proposal for such a process and starting
conditions? I’m skeptical of the assertion.

> Right now, at this moment who knows what our goals are for the Release
> of the Specifications? Have we decided which sets of features must be
> included for this release? What is the critical path? Deadlines? I am
> not aware of such agreed-upon and documented decisions.

In my experience, specification development by a committee of volunteers
goes through a series of stages. Initially, the committee imagines it
has all the time in the world and everything is possible. Wild ideas are
proposed. Work begins. Some ideas turn out to be impractical. Some ideas
turn out to be wrong. Some ideas are enthusastically supported, adopted,
documented, and become part of the specification. Different participants
see these ideas differently, combine them in new ways, make new
proposals.

Eventually, the rate of new proposals slows. It turns out some of them
are damned hard work to document, test, and implement. A consensus forms
that what’s been done so far is “enough”. Enough has been done that most
people in the committee feel like the user community would be pleased if
we wrapped that up and put a bow on it. 

Then the next phase of really hard work begins. All of the tedious
detail has to be ironed out. Implementors discover ambiguities that
weren’t previously noticed. More compromises have to be made. New
proposals are made to resolve ambiguities and clarify the spec. On a
good day, that’s easy. On a bad day, the group decides to tear out a
whole feature and replace it with something new.

Would we make better progress if we agreed in advance on a set of
features? Maybe. But that wouldn’t stop individuals from proposing new
features. And if the new feature is good enough, there’s nothing that
would prevent the committee from adding it to the list.

Would we be finished sooner if we agreed on a deadline? No, I don’t
think so. Pick a date: December 31, 2024. Stipulate that we have all
agreed that we *must* ship by that day. Would we ship by that day?
Probably not. There’s no *actual* consequence for missing the deadline
and we’re all volunteers so the speed with which work gets done is the
speed at which it gets done. And you can’t ship half a specification, so
it ships when it finishes.

Eventually, the committee will decide that it’s tired and wants to go
home. It will become progressively more hostile to proposals that add
new features. The hardy among us will hang on with determination to see
it through. Maybe we’ll get there by December 31, 2024, but I wouldn’t
count on it.

> Without such clarity we still may produce a lot of good work, but it
> would be much less coordinated and efficient.

I am open to any concrete proposal you might have for improving
coordination and efficiency.

> The difference in the approach to the specification-design process
> might explain why some PLs have a major new release almost every year
> but the last X___ specifications were produced 10 years ago.

Most of that ten year gap can be explained by the fact that we all took
a break. Since the working group that produced X____ ten years ago was
dissolved, the group that is working on the next release has had 37
meetings. I think we’re doing pretty well for a bit more than six months
effort, to be candid.

> This frankly reminds me of the Zeno's paradox 😄

Zeno’s paradox isn’t “this is taking longer than I think it should”. :-)

                                        Be seeing you,
                                          norm

[1] https://github.com/qt4cg/qtspecs/issues/536

--
Norm Tovey-Walsh <ndw@nwalsh.com>
https://norm.tovey-walsh.com/

> Art happens—no hovel is safe from it, no prince may depend upon it, and
> vastest intelligence cannot bring it about.--J. M. Whistler