[SM-Discuss] Tome nominations

seth at swoolley.homeip.net seth at swoolley.homeip.net
Thu Aug 28 19:52:43 EDT 2008


On Thu, Aug 28, 2008 at 04:53:35PM -0500, Jeremy Blosser wrote:
> On Aug 28, seth at swoolley.homeip.net [seth at swoolley.homeip.net] wrote:
> > I think the first role of any tome lead is to ensure our own developers can 
> > work their way around the system.
> 
> I'm not trying to sound overly concerned about the way documentation is
> produced.  The bottom line to me is that we need doc maintenance and
> whoever finally starts producing them should do what works for them.  I
> think the first (and really only) role of the tome lead is to make sure we
> have adequate documentation.  While we don't chase after users that need
> their hands held, that mostly speaks to the type of documentation needed,
> not the method by which it's be produced.
> 
> I was primarily saying I'm interested in hearing if the nominee(s) have
> concrete ideas on how they intend to make sure something actually starts
> happening, instead of more sound and fury signifying nothing.

You're right, of course, but I think anything that makes it easy to document 
inline with the development process improves resultant documentation.  Some 
of that simply may involve process and policies.

One of the things documentation people can do is watch the commits and make 
sure changes are documented.  If that's not happening, then they can work 
with, for example, sorcery lead, to make sure changes there make their way to 
the website.  They can also watch the general grimoire changes to see if 
major components had changes and ensure that people are abreast of them, both 
in changelogs, and with a newsletter (integrated with the website, of 
course).

There is a lot of stuff to document, not just statically, but as things 
shift, so documentation is kept up-to-date.  I think some matter of policy 
work will be involved, and training people in policy so that it becomes 
habitual and reinforced by gurus who are assimilating new developers.

So a leader that can help developers stay on task with documentation concerns 
would be a good start.

As far as the comment that "it shifts too much to document", re cauldron.  I 
don't expect final documentation when you write it, although good design 
necessitates some design documentation up front, but before it's released to 
stable, it should have solid documentation around it so that people who 
haven't been observing test will see exactly what to do.  Administration 
isn't necessarily configuration only.  Upgrade handling is the second half of 
it.

I'm hoping we can have this discussion now so that when we do hear the 
"speech", that we might have a good idea of what we can expect to hold him 
accountable to. :)

Seth

-- 
Seth Alan Woolley     Pacific Green Candidate for Secretary of State
                                                http://seth4sos.org/
State Coordinating Committee Member
Secretary and Parliamentarian               Senior Software Engineer
2008 Elections Administrator            Rich Map Compiler and Engine
Pacific Green Party of Oregon        deCarta: Powering LBS Solutions

IANAL (I am not a lawyer!)         TINLA (This is not legal advice!)

3403 NE Stanton St   gnupg.org key 84317E6A =   http://swoolley.org/
Portland, OR 97212   8C97 9818 F889 EDE3 B54C   Cell: (503) 953-3943
USA, 97212-2744 03   AAD6 E936 BF83 8431 7E6A   45.5438 N 122.6295 W


More information about the SM-Discuss mailing list