[documentation] Quick question...

[Larry Garfield]

Fix the code snippet (if appropriate) and delete the comment is what I 
generally do.  I've also been known to revise a page to include multiple 
snippets if they're related ways of doing the same thing.

I generally work on the principle that comments in the books are bad, and 
should be removed in whatever way is most expedient and useful. :-)

On Friday 11 May 2007, pyutaros at idkd.net wrote:
> Thanks for the answers.  Very clear direction laid out there.  What about
> situations where folks are reporting errors with code snippets?  What does
> everyone else think about these situations?
> Jonathan
> (pyutaros)
>
> > Hi Jonathan,
> >
> > Here's a quick response ;)
> >
> > 1) Generally the way I deal with these is to make the other code
> > sample comments into child pages of the original.  I just copy and
> > paste the comment into a new child page, cleanup the text to read
> > more like a page than a comment if necessary and give it a title that
> > makes sense in the book.  Also give the comment author credit in the
> > log.
> >
> > 2) SoC pages should just be left alone.  They aren't really part of
> > the handbook and the conversations need to be preserved.  We are
> > looking at ways to get them removed from the pages with comments
> > listing.
> >
> > Hope that helps some and if others have suggestions, feel free to
> > speak up.
> >
> > Thanks
> > Addi (add1sun)
> >
> > On May 10, 2007, at 4:52 PM, pyutaros at idkd.net wrote:
> >> On some of the document pages it can be a little unclear what to do
> >> with
> >> the comments.  here are two specific examples:
> >>
> >> http://drupal.org/node/81242
> >> HOWTO: Display your node's "last edited by" information.
> >> The author submitted PHP code exemplifying one way to accomplish this.
> >> The comments submit code listing other ways of doing the same thing
> >> or for
> >> doing slightly different things.
> >>
> >> http://drupal.org/node/58959
> >> Child -> Parent(s) Relationships
> >> This was a proposed project for the summer of code 2006.  There is
> >> a short
> >> discussion that sparks up, but is never really resolved.
> >>
> >> What should be done with comments in these situations?  It seems
> >> like you
> >> would want to preserve discussions or alternate ways of code.
> >> There are
> >> also pages where user's report errors with code listed in
> >> snippets.  Do we
> >> have a standard way of addressing these kinds of things?
> >> Thanks,
> >> Jonathan
> >>
> >> --
> >> Pending work: http://drupal.org/project/issues/documentation/
> >> List archives: http://lists.drupal.org/pipermail/documentation/
> >
> > --
> > Pending work: http://drupal.org/project/issues/documentation/
> > List archives: http://lists.drupal.org/pipermail/documentation/
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/


-- 
Larry Garfield			AIM: LOLG42
larry at garfieldtech.com		ICQ: 6817012

"If nature has made any one thing less susceptible than all others of 
exclusive property, it is the action of the thinking power called an idea, 
which an individual may exclusively possess as long as he keeps it to 
himself; but the moment it is divulged, it forces itself into the possession 
of every one, and the receiver cannot dispossess himself of it."  -- Thomas 
Jefferson