Skip to Content.
Sympa Menu

sm-discuss - Re: [SM-Discuss] Tome nominations

sm-discuss AT lists.ibiblio.org

Subject: Public SourceMage Discussion List

List archive

Chronological Thread  
  • From: seth AT swoolley.homeip.net
  • To: sm-discuss AT lists.ibiblio.org
  • Subject: Re: [SM-Discuss] Tome nominations
  • Date: Thu, 28 Aug 2008 16:52:43 -0700

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




Archive powered by MHonArc 2.6.24.

Top of Page