Tutorial collection/end-user docs

[Joseph R. Justice]

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

> So, officially I'd like to announce the start of "KDevelop Book".
> Everything in the wiki should be set up to start writing.
> Here's the link again: http://grunz.bplaced.net/kdevwiki/
> Don't hesitate to tell everyone about this ;-)

Hi.  First off, you don't know me, I'm not a contributor to KDevelop,
but I've been following the -devel mailing list for a few weeks now.
Secondly, I have _NOT_, repeat _NOT_, looked, at *all*, at the web
site provided, so some or all of the following may be, basically,
bogus.  (If it is, please say so, I won't be offended.)  Lastly, while
I do consider myself a Pwoh-Gram-Mah (tho sadly out of the loop these
last several years, I haven't done anything I.T. or C.S.-ish for
several years now unfortunately), when I *was* programming I was doing
stuff related to document massaging where the content was in SGML (the
predecessor to XML), including creating stuff for the web (tho, not
anything modern like the various Content Management Systems I read
about, this was all home-grown stuff, before the time of that).  So,
that's where I'm coming from.

My thoughts following relate primarily to, frankly, unsexy
infrastructure issues, and not to anything sexy or really interesting,
like real content related to the proposed book.  I apologize for not
bringing this up sooner, but hopefully it's not too late to mention
these thoughts.


First off, I enthusiastically and whole-heartedly agree with the idea
and goals of this.  If and when I'm ever set up to try to use
KDevelop, I'm sure this would be an invaluable resource for me.  I
hope this succeeds.

Second off, I understand how ... easy to use, to just start
_generating_ stuff, a wiki can be.  How approachable and
unintimidating it can be.  (I've contributed, a very little bit, to
Wikipedia and to a few much smaller wikis.)  I realize how attractive
a wiki is, especially with its ad-hoc and immediate feedback nature.

And, third off, I realize that he (she) who contributes the effort and
resources gets to decide how they're used, code talks louder than
words, etc.  I'm certainly not in a position to contribute effort or
resources at this time (heck, I've never even _used_ KDevelop).


But...  All the same, I have two thoughts I'd like to offer,
concerning this project.

First, I'd like to encourage you to, before this gets going big with
(possibly) lots of contributors, figure out what sort of licensing /
copyright this is going to be under.  I *presume* that it's going to
be something compatible with FOSS software, since KDevelop itself is
FOSS.  However, there's still lots of possibilities, ranging from GPL
or LGPL, to GFDL, to one of the Creative Commons variants, to some
other explicit license altogether, to simply explicitly public domain.

I know you know this already, because it's much the same as with
program source code, but...  Depending on what you want to do with the
content, how you want to make it available and who you want to allow
to (and/or be willing to) redistribute it, how you want to be able to
reuse it or parts of it for other purposes (code segments embedded
within the documentation, for instance), can affect what specific
licenses are better suited for the work.  Conversely, the license you
pick now can affect what you can later do with and/or how you can
reuse the content, including things you haven't even thought of yet.
And, it can be a Real PITA to try to relicense the content later, if
you determine you need (or want) to do so, especially if you have had
lots of contributors to it in the meantime, perhaps including
contributors you do not at that point know how to contact (even if
they'd be willing to relicense if you did know how to contact them).

As a specific example of this, the PITA-ness of relicensing your
content under a more suitable for your purposes license, I refer to
the hoops Wikipedia had to jump through to relicense their content
under a license they determined was more suitable for what they wanted
to do, a year or two ago.  My understanding is that it wasn't easy or
trivial.

To this end, I'd suggest you look at and/or contact organizations who
you expect you would like to have distribute this content, if and when
it gets good enough for that purpose, to see what licenses they
suggest or recommend, or other thoughts they have to offer related to
licensing.  Some obvious organizations I can think of off the top of
my head are:

* the Linux Documentation Project,

* the Debian Project and specifically their legal / licensing and
their documentation interest groups (IIRC, they've determined that the
GFDL, or at least certain variations of it, is insufficiently "free"
for their purposes and any documentation licensed as GFDL has to be
provided in the "non-free" section),

* the corresponding interest groups for other major Linux
distributions (Fedora, OpenSUSE, Ubuntu, Gentoo, etc) and other FOSS
operating systems (the BSD variants, OpenSolaris, etc), or at least
ones you want to officially support using KDevelop on, and

* the applicable documentation interest group for KDE itself.


Second, I'm not sure it's the right idea, at least not the right idea
_long_ term, for something possibly intended to be a "book" or a large
document or collection of documents, for the *content* (or "source
code") of the book to be implemented as a wiki.  (This, as opposed to
the "binary" result, intended for people to actually use.)  I wonder
if, long term, it should be "developed" (written) in XML, probably
using a major XML DTD like Docbook, and then converted into whatever
end-result(s) you want to have.  This is because using XML, or
something similar, would allow you to concentrate on the structure of
the document, the actual content of it, rather than on its
presentation or how it looks.

I know it requires infrastructure and training, both on the part of
the individual contributors and on the part of whomever is running the
project as a whole, to use XML for something like this.  But, if you
take the time to set the infrastructure up and use it, you can get a
lot of benefits:

(1) It's relatively easy to convert from XML to almost any document
end-result you can think of: plain ASCII text, HTML, PDF, TeX/LaTeX,
print, wikis, etc.

(2) As mentioned above, XML is (generally) only concerned with the
structure / content of the document, not with its formatting and
style.  (At least, if you use it properly.)  I see people worried
about HTML and CSS codes -- that would be an issue for the document
conversion step from XML to HTML, and not so much for the raw
generation of content.  Also, different output formats, such as plain
text, PDF, and HTML, typically will require different formats and
styling for a given piece of structure (such as a heading or
subheading, a list, or a segment of source code) -- rather than have
to embed all this into the source of the document, and keep it all in
sync throughout the document, you can let the software responsible for
converting the document from XML source to the selected output format
worry about that.

(3) It's relatively easy to take chunklets of XML, at least XML using
a major (not home-grown) DTD, and re-use it elsewhere in other
XML-based documents or for other purposes.

(4) It's (almost) all text (modulo binary chunks like pictures, sound
files, video files, etc) and is therefore easy to manage using a SCM
(like git, etc).  With this, you could tag versions of the book, e.g.
"This is the book for v 4.0.0", "this is the book for 4.0.1", "this is
the book for 4.1.0", etc.  And, with something like git, you can have
multiple contributors each pushing their changes to the book source
repository, and unless there's conflicts (multiple people each editing
the same section at the same time) there shouldn't be a problem with
them all working at once.

(5) It should be easy to generate tables of contents, tables of
tables, tables of code segments, etc, and multiple indexes (indices)
as needed.  Also cross-references, footnotes, sidebars, etc.

(6) If there's code segments, etc, it should be easy to pull them out
and validate them as appropriate.  Or, if you want to say "This code
segment should generate the following result / behavior / display" or
"This is what happens given the following code segment", even up to
and including screen shots and the like, it should be possible to
programmatically verify that, and/or simply generate the screen shot
automatically from the code segment itself.

(7) With respect to translations, internationalization, and
localization, I'd think it ought to be at least as easy, if not
easier, to manage this using documents structured with XML as it would
be with a wiki.  Ideally, you could keep translations in sync down to
the paragraph level.  (I don't know that something like Docbook
supports this, but it might.)

There's lots of infrastructure already existing to create and manage
XML documents, both on the client / writer side and the server side.
And, much of this infrastructure is available as FOSS, so there's no
direct financial cost to using it.

For more information on this topic, I'd strongly encourage you take a
look at what the Linux Documentation Project has to say and what
information and resources they can offer.  After all, "this is what
they do", you know?


Hope this is of some use, interest.  Thanks for giving me a few
minutes of your time.  Be well, take care, do good things.


Joseph