Re: [MI non-stop 0/11] Series overview

[Stan Shebs <stanshebs at earthlink dot net>]

Vladimir Prus wrote:
> Eli Zaretskii wrote:
>
>   
> > > From: Vladimir Prus <vladimir@codesourcery.com>
> > > Date: Sat, 28 Jun 2008 20:33:27 +0400
> > >
> > >
> > > All patches are ready to be committed, except the patch for enabling non-stop
> > > with a single command -- that one needs discussion.
> > >       
> > What about documenting the new features?
> >     
>
> Why do you think the MI non-stop spec and the thread behaviour spec were written? 
> As usual, and even more than usual due to huge amount of text, I'm not going to 
> mess with texinfo until I'm sure nobody has big objections about the behaviour.
>   
I'm with Eli on this actually. I can sympathize with the desire not to 
waste time writing about code that won't go in, but if as you say, the 
patches are ready to be committed, and the basic design has already been 
approved, then it seems pretty likely that any documentation text will 
receive at most minor changes. The specs are good to have too, but 
they're not really a replacement for user documentation; in fact they 
should be fodder for the internals manual.

A beneficial side effect of preparing doc text with the code is that it 
helps reviewers relate the code changes to intended observable behavior, 
whereas the spec might or might not be out of date, things having 
changed due to implementation issues or feedback on related work.

Stan