[CRISP-TEAM] Alan Barrett's comments on the BW7 draft.

[Alan Barrett]

On Thu, 15 Jan 2015, Bill Woodcock wrote:
>> On Jan 15, 2015, at 3:55 AM, Alan Barrett <apb at cequrux.com> 
>> wrote:  1. I think that the cover letteer should be in a 
>> separate document.
>
> I disagree.  I believe that our eventual primary work product 
> should be a single PDF file containing everything in one.  If we 
> split things into separate files, they will inevitably become 
> disassociated in the future.  I don’t think it matters much in 
> the one-week timeframe, but I think this is very important in 
> the two year + timeframe.

I won't insist on separation, but I do think that two separate 
documents would make sense.  When I print the proposal, I don't 
also want to print the cover letter.  When I view the proposal 
on a web site, I want to see the revision control section at the 
beginning, not after a cover letter.

Most of the content of the cover letter is or could be repeated in 
the Abstract, if you are concerned about context being lost.

>> 2. In the table of contents, only the top level headings have page
>> numbers.  I suggest also adding page numbers for second-level headings
>> but not for third-level headings.
>
> I started that way, of course, and found it was too cluttered to 
> be legible, but that’s a matter of personal taste, and as in 
> all things, I’ll defer to the consensus… I also tried making 
> everything below L1 enumerated but much smaller, or in gray, and 
> neither of those seemed to be improvements.

OK, if you think it's too cluttered, you are probably right.  I 
haven't seen what it would look like with more page numbers.

I'd put the table of contents after the abstract, but I'll defer 
to your judgement here too.

--apb (Alan Barrett)