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

[Vladimir Prus <vladimir@codesourcery.com>]

On Saturday 28 June 2008 21:44:09 Stan Shebs wrote:
> 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.

Well, since we're talking about MI -- which is fairly formal protocol itself,
spec is very close to what will come in documentation.

> 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.

By my book, spec that's not up-to-date is not a spec :-)

- Volodya