Tutorial collection/end-user docs

[Joseph R. Justice]

On 12/4/10, Syron <mr.syron at googlemail.com> wrote:

> Wow, I think this was fairly one of the longest mail to this list
> without patches or stack traces!

I'm ... verbose.


> There are very interesting things inside, ie. the thing about content
> representation and managing, and also the big licensing question.

Thank you.  I'm glad I was able to raise some interesting questions.


> The first thing to answer: I decided to use the mediawiki, because I
> haven't yet found any other system that would allow quick creating of
> content. Yes, I thought about using source control for this project,
> given a simple HTML template, but that would have worried the "average"
> user.

Right...  See, I get the idea of immediate and positive feedback.  I
do.  It encourages interaction and involvement.  And, perhaps that is
most important, when getting started.  It's in the vein of "release
early and often", I think.

What I'm saying is that, from a _longer term_ perspective, something
that's more structured and more infrastructure -using / -leveraging
might prove to be more maintainable and more useful over that longer
term, and perhaps longer lived as well.  Just as is the case for
software and program source code.  There's a Whole Host of
already-developed tools out there intended for people doing
documentation, might as well make use of them.

Now, it might well be the case that the best way to go is to get a
self-sustaining amount of initial content created using the / a wiki,
with the expectation that at some point it'll be converted into
something more structured.  And, perhaps with some sort of way to go
the other way as well, transforming from the structured format back
into the wiki.  That could allow you the best of both worlds, at least
possibly.

I also note that the Linux Documentation Project has itself apparently
started to make use of a wiki, and is trying to use it for maintenance
of some of the LDP's documents, converting from wiki to Docbook and I
*think* also back again.  (I was not aware of this prior to writing my
previous message.)  I don't know how successful they've been with this
to date, but it might be worth checking out.


> Your idea of making this content management more
> representation-independent by using some markup-like thing brought me to
> an idea, maybe I'll create something cool.

I'd strongly suggest trying to use something, anything, that already
exists rather than create Yet Another Markup Thing.  I mention XML
because I'm most aware of it, but there's lots of other stuff out
there if you don't like XML.

Unless you're Really Into the idea of building some sort of
documentation creation tool set for its own sake, it just makes more
sense to use something somebody else has already built and knocked the
worst of the bugs out than to build something yourself which you'll
have to debug before you can use it in the first place.  Well, unless
you're Donald Knuth, I suppose, but he's a special case.


Hope this is of some use, interest.  Thanks for your time.  Be well.


Joseph