Mailinglist Archive: opensuse-marketing (277 mails)

< Previous Next >
Re: [opensuse-marketing] The openSUSE Handbook proposal
  • From: Klaas Freitag <freitag@xxxxxxx>
  • Date: Wed, 6 Oct 2010 16:56:00 +0200
  • Message-id: <201010061656.01050.freitag@xxxxxxx>
On Wednesday 06 October 2010 01:26:44 Christian Boltz wrote:

Hi,

I still think using the wiki wouldn't be too hard (with some creative
template usage), but I also like your idea of using a WYSIWYG XML
editor.
Frank said in another mail in this thread that it does not make sense
to maintain documentation in more than one source. I completely agree
on this. But IMO that also means that the Wiki is the only source we
can use for that.
The reasons are
- Wiki gets most contributions and as a result has the most documentation
- Wiki is most recent
- Wiki is state of the (community) art.
These are facts we can not ignore, and the Lesson for Lizards proves that.

However Franks concerns against Wiki are very valid, especially when it
comes to structure. In the new wiki we have structure, which is great,
but I agree to Frank that this wont be enough for a book.

But why not use both: Wiki as a source for content and the susedoc system
to create a book? I see that this sounds like a scary idea, but why not
brainstorm about a "book description file" which defines a structure for
the book, names the source pages in the wiki, possibly patches to apply
to the downloaded wiki page content, and finally generate XML that is the
source of the book?
So we would get the benefit out of the quickly moving wiki content for the
book. I know, that sounds very uncooked, it is of course, but still a
neat idea, or not?

Generally I am wondering why we discuss so much about technology here. Isn't
it great in general if people stand up and want to contribute content, which
is the most important for documentation I think? So the format in which the
(good) content is delivered does not really matter as long as the quality
is high. Converting something to the right format shouldn't be the main
effort, right?

So shouldn't be the discussion "What is good documentation?" stand
in front?

I think we should "split" the potential editors in two groups:

a) people that want to do large contributions, for example a new
chapter about <insert topic here>

They will probably have no problem with learning the needed XML, and
they'll probably also fit your "want to learn something new".
Even if they initially didn't want to learn XML, the effort is small
compared to writing all the text, and therefore acceptable.

b) people that "just" want to fix a small error or a typo

I doubt that they will happily learn XML "just" to fix a typo or mark
a link as a link - the effort to result quotient is too bad in this
case ;-)
For those people, having an "Edit" link in the online version of the
manual would be a very big advantage.
Couldn't we find people for these two groups instead:
- Editors: People who work on content and deliver in which format they ever
want (nearly ;-) to
- Book Builders: People who get the content from the Editors and work on
building a book with the best suited tool for that?
Maybe it makes more sense to devide the "good-writer-skill" from the "I-like-
to-fiddle-with-tools-which-produce-great-outcome" role?

regards,

Klaas

--
To unsubscribe, e-mail: opensuse-marketing+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-marketing+help@xxxxxxxxxxxx

< Previous Next >
List Navigation
Follow Ups