[SM-Discuss] Tome nominations
Elisamuel Resto
samuel at dragonboricua.net
Tue Sep 2 22:38:13 EDT 2008
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
More information about the SM-Discuss
mailing list