Public SourceMage Discussion List

[Elisamuel Resto <samuel AT dragonboricua.net>]

Mark Bainter wrote:
> Jaka Kranjc [smgl AT lynxlynx.info] wrote:
> > Users we've never heard from contribute to the wiki. Even kids! :) And you 
> > don't have to contribute to documentation regularly to make it count. If 
> > someone does a wiki commit and then disappears, that's perfectly fine and 
> > even great (the contribution part).
>
> How often does this happen, and how valuable are these contributions?  I 
> would think the majority of *our* userbase would be more than
> technically capable of checking out a repo, making a change, and
> submitting a patch.  Especially if we had a basic doc procedure to
> follow.
>
> However, beyond the technical problem is the time committment problem.
> If a user is looking at the site, and sees in the docs something that
> isn't really correct anymore, how will they respond?  If it's just a
> wiki, and all they have to do is click to edit the doc, make the
> correction, and save it - they'll probably take the time to do it.
>
> Lets consider an average user under a latex scenario.  They see the
> problem, and determine to take some time to fix it.  They search the
> site and discover they need to use git to make the change.  Ok, no
> biggie, lets assume they already have git installed anyway.  They clone
> the repo.  Oh...it's in latex.  They go back to the site and look at our
> handy latex quick reference and then make the changes.
>
> Oops, they don't have a latex environment to test it.  Now they have to
> go build the LaTeX tools.  Ok, that's done, now they test it and it
> fails.  They figure out the errors, make the corrections, and now they
> can finally commit it to the repository.
>
> Or...alternatley...they don't bother trying to test it, and commit it to
> the repository broken, and someone (probably the lead) has to come along
> behind and fix all the broken markup before a new release can be made.
> In that setup we certainly can't automate updating the site code.  (We
> could of course try to force it to build before allowing the commit, but
> that just takes us back to scenario 1).
>
> Now, for someone who just wants to note that a single command has
> changed from X to Y are they really going to go through all of this?
> No, somewhere along that path they're going to decide it's not worth it,
> and it's not going to get done.

Mark, David and Jaka have pretty much expressed all my thoughts on the 
points brought up on the thread.

I don't think this complexity is needed at this point (the starting 
point) but might be useful further down the line. Right now, the *only* 
thing I can see use for is the git-editing of the wiki files, and I 
doubt I'll use it constantly.

LaTeX, DocBook, etc. will be useful when we have a set of documents that 
we might need them translated to $language and maintenance will start 
becoming a pain in the ass. I am more inclined towards DocBook rather 
than LaTeX at the moment, but that might change when I research further 
down the line.

-Elisamuel