[documentation] Proposal for handbook maintenance automation

Laura Scott laura at pingv.com
Wed Aug 8 17:34:04 UTC 2007


Personally I think relevant handbook corrections / suggestions should  
remain on the page in question, to the extent possible. Having a  
separate list for corrections loses the possibility to have a frank  
and open exchange of ideas on the handbook page itself. Many times a  
comment on a handbook page has offered a clarification or correction  
to the page itself and saved my butt -- and that would not have  
happened had the correction been placed in an issue queue elsewhere.

<alternative possibilities - flagged to avoid thread hijacking>

Using node reference to provide a direct link to the issue queue from  
the handbook page itself might be helpful, but only if the visibility  
were both ways (e.g., view issues reported on this handbook page,  
kind of like for the project pages), but this itself might get  
unwieldily too.

I seem to remember somewhere reading about an annotation  
module ;) ... and wonder if an adaptation of that could lead to an in- 
line parallel class of comments for handbook pages where people can  
make notes that are purely related to corrections. I'm not convinced  
this is the best idea, or even workable from a usability-on-a-mass- 
scale perspective, but the general idea has been tickling me since  
reading that chapter of PDD.

</alternatives>

Laura



More information about the documentation mailing list