[SM-Discuss] Tome nominations

flux flux at sourcemage.org
Thu Aug 28 16:45:41 EDT 2008


seth at swoolley.homeip.net (seth at swoolley.homeip.net) wrote [08.08.28 16:34]:
> On Thu, Aug 28, 2008 at 12:30:15PM -0500, Jeremy Blosser wrote:
> > On Aug 23, Elisamuel Resto [samuel at dragonboricua.net] wrote:
> > > Haah... really, you guys... no time to rest.
> > > 
> > > Well, I do accept said nomination, but I'm no good for speeches, and
> > > also givent hat Tome has been blank for a while, my goal is not so big
> > > as to get us a full set of documentation, but to at least get the
> > > process moving into that direction.
> > 
> > I would like to hear some specifics of what things you plan to do, and what
> > areas of docs you plan to focus on first.
> > 
> > For a while I have thought the most direct way for us to get more devs
> > involved in documentation is to make it so they can do docs as they do
> > spells; that is, get a git documentation repository that pushes directly to
> > moinmoin's backend (which uses flat files and should support this kind of
> > thing.)  Do you think this would do any good, or no?
> 
> I agree with you, Jeremy.  The distro is for developers/admins by 
> developers/admins, so we should support documentation by and for them.
> 
> I think the first role of any tome lead is to ensure our own developers can 
> work their way around the system.  If it so happens that we complete that 
> goal, then we can move on to potentially increasing the userbase into 
> non-technical folk, however, I think the entire design philosophy precludes 
> such an eventual path unless a separate organization makes a user-friendly 
> variation with much more limited options and strict QA testing.
> 
> Seth

I also agree, but I also disagree. I may seem incoherent about this, but
here are my thoughts. I'm definitely all for having a git repository for
documentation, and I have been in favor of a git backend for our wiki
since I first heard it suggested, so definitely a +1 for all of this.
However, I think the reason we have a need for a Tome team in the first
place is that most developers are either too busy or not concerned
enough to produce the documentation in the first place. Therefore, while
I think that developers *should* be doing documentation, I also
recognize the fact that it largely may not be done by them for various
reasons. For example, I myself have tried to produce as much
documentation as I can for cauldron, but there is so much need for raw
development that I simply don't have time to produce as much
documentation as is needed. I think if we get a dedicated team of
documentation producers to ease the burden on the rest of the developers
this would be a great help. Beyond that, the Tome team can manage ways
to make it easier for the rest of us to help push out what we can. I'm
not sure if I explained myself well, so feel free to ask me to clarify
anything that is unclear.

-- 
Justin "flux_control" Boffemmyer
Cauldron wizard and general mage
Source Mage GNU/Linux
http://www.sourcemage.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 489 bytes
Desc: not available
Url : http://lists.ibiblio.org/pipermail/sm-discuss/attachments/20080828/7af70617/attachment.bin 


More information about the SM-Discuss mailing list