[documentation] Proposal for handbook maintenance automation

[Ben Feldman]

Dave Chakrabarti wrote:
> Thought: If there's a typo on a page, would someone use the same 
> system? While I love the idea of creating a prominent "report this 
> page for updates" link / button, I think we'll end up with pages 
> reported without a clear idea of whether it's a one-line typo / 
> grammar error or a multi-paragraph rewrite.
Yeah... that wouldn't be good.
>
> I'm a doc newbie, of course, so take this with a grain of salt :)
So? In fact, we should weight newbies' thoughts more than vets'. The 
newer you are, the more your mindset is like that of a casual visitor 
looking through the handbook.
> Maybe adding a comment field with "Submit suggestions for updates" 
> would encourage readers to add a specific update instruction?
That would be perfect. Along with the comments box, should the user also 
be able to choose the priority? To help them decide which one is right, 
I guess we could have a few examples there, like critical is broken 
code, minor is typo, and normal is something in between.

Possible format:

Issue title: "Page Title updates requested."
Submitted by: whoever submitted it -- Should the user have to be logged in?
Project: Documentation
Component: whatever component
Category: task
Priority: whichever the user chooses
Initial status: patch (code needs review)

Description: "User whatever requested that the Handbook page 'Page 
Title' in Component be updated.

Comments: whatever the user put in"

What do you guys think?
>
> Hope this helps,
>
>   Dave.
>
> ------------------------
> Dave Chakrabarti
> Director of Programs
> Grassroots.org
>
>
> On Aug 8, 2007, at 10:01 AM, Ben Feldman wrote:
>
>> Greg Knaddison - GVS wrote:
>>>> Also, I think if a common user could flag a handbook as "needs updated",
>>>> it would come in use.  Before I was a maintainer, I viewed handfuls of
>>>> handbook pages that needed updated, but I didn't know who to notify.  It
>>>> would be useful to have a link for "needs updated", or something
>>>> similar, so that maintainers could be notified.  All flagged handbook
>>>> pages would be compiled into a page, sorted by number of flags.
>>>>     
>>> This sounds great to me as well.  We have the "suggest documentation
>>> improvements" link in the bottom of the left sidebar along with a
>>> couple other things.  I'd prefer seeing that in the content area just
>>> under each handbook page and above any comments.  That's the place
>>> where people will be thinking about it and might act on it.  The
>>> bottom of the left sidebar is a place where, even after viewing
>>> hundreds of handbook pages, I didn't know it existed
>> I think this is an absolutely great idea! And while something similar 
>> exists, I think the fact that it sends you to the issues page would 
>> either be too confusing, or seems like too much work--like you'd have 
>> to point out what needs to be updated and what it should be updated 
>> to, if you know what I mean.
>>
>> How about this? There is a simple "Add page to update queue" link 
>> (with better wording) at the location you noted, Greg, that when 
>> click automatically adds an issue to our Issues page with simply a 
>> link to the handbook page and a little text saying "such and such a 
>> user submitted this handbook page for updates."
>>
>> I, too, would be more willing to act upon old information if this 
>> kind of a system existed.
>> -- 
>> Ben Feldman
>> Director, Go FLOSS!
>> ben at go-floss.org
>> --
>> 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/

-- 
Ben Feldman
Director, Go FLOSS!
ben at go-floss.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20070808/35823156/attachment-0001.htm