[SM-Discuss] Tome nominations
Elisamuel Resto
samuel at dragonboricua.net
Thu Aug 28 23:31:33 EDT 2008
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
More information about the SM-Discuss
mailing list