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: Elisamuel Resto <samuel AT dragonboricua.net>
  • To: sm-discuss AT lists.ibiblio.org
  • Subject: Re: [SM-Discuss] Tome nominations
  • Date: Thu, 28 Aug 2008 23:31:33 -0400

seth AT swoolley.homeip.net wrote:
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

Hey,

Pardon my delay, I changed boxes and had forgotten to install a mail
client. Thanks Juan Carlos for alerting me.

My initial aim is to get the most-needed documentation in a usable and
easily-accessible form... this includes installation routines,
post-installation documents and other related documentation (like the
hardware pages, the howto's [ex. the postgresql one]). After that, is
getting the rest scrutinized and organized.

Now, in regards to the Git-based backend for the wiki, if it is possible
to have it and still keep up with the upstream versions without needing
to rewrite it for each bump then by all means it's a good idea. We don't
want to do a horrid amount of work for the complexity it might bring, if
it's not used much. I personally prefer some other method, as discussed
with Justin and Juan Carlos on IRC... like DocBook or LaTeX. However,
for now I want to focus on the above-mentioned tasks.

Right now, what is needed is a MoinMoin upgrade, the activation of the
Xapian indexing engine (to which I made changes to the spell to make it
work with our moinmoin spell) for faster/less-load searches and being a
bit stricter with the ACL's. I am not saying lock the wiki to some users
only, but writing pages to registered users only. The amount of WikiSpam
we get is annoying. This is a talk for later on, as I have a few
suggestions on this area.

Once again, pardon for the delay and also for the "brain dump" type of
message, but I have problems expressing complicated thoughts. This is
the most condensed/understandable way I can express them for now.

-Elisamuel





Archive powered by MHonArc 2.6.24.

Top of Page