Re: [opensuse-marketing] The openSUSE Handbook proposal

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [opensuse-marketing] The openSUSE Handbook proposal

Frank Sundermeyer
On Thu, 30 Sep 2010 00:54:30 +0200 Jos Poortvliet wrote:

Hi,

> On Thursday 30 September 2010 00:26:09 Helen wrote:
> > How hard is it to convert to multiple e-reader formats including
> > PDF?
>
> That is actually a pretty good point. If our Wiki is good enough in
> terms of content, we can try and figure out how to automate creating
> a book. Well, fully automatic would probably be hard - a book would
> need a bit of layouting. But having all the content on the wiki, then
> using it for a complementary book - I think that's the way to go.

I completely disagree. You are proposing to create documentation in a
completely unstructured format and then writing parsers attempting to
create an exchangeable format.

It is re-inventing the wheel by starting with a rectangle.

We already have all the style-sheets for XML to provide the formats we
need (including wiki text).

--
Regards
        Frank

Frank Sundermeyer, Technical Writer, Documentation
SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg
Tel: +49-911-74053-0, Fax: +49-911-7417755;  http://www.opensuse.org/
SUSE Linux Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg)
"Reality is always controlled by the people who are most insane" Dogbert
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [opensuse-marketing] The openSUSE Handbook proposal

Thomas Schraitle-3
Hi,

(CC'ed opensuse-doc so doc people can read that too.)

On Monday 04 October 2010 Christian Boltz wrote:
> [...]
>
> I'm not sure about that. I don't say that it will be very easy, but it
> should be possible, and it won't be too hard.

You are underestimate the efforts.

 
> 90% of the formatting can be done with plain wikitext, and for the
> remaining 10% templates can be used (which can, but don't have to have a
> visible effect in the wiki). A "visible" template might be something
> like "text printed on screen", an "invisible" template might contain a
> keyword for the book index.

We use a feature in DocBook/Novdoc what is called "profiling". We label one
paragraph for business related products and another one for openSUSE products.
When we process the manual, the paragraphs are being "filtered" so only the
requested product is visible in the end format. Maybe this belongs to the
remaining 10%...

 
> I think we could even develop a "XML skin" for mediawiki so that the
> wiki can generate valid docbook/novdoc XML out of wiki pages (with
> <para> instead of <p> etc.).
> The alternative solution would be to post-process the wikitext or the
> HTML to convert it to XML.

Depending on the HTML this sounds scaring.


> Basically the two methods don't differ too
> much, the main difference/question is if you want XML output integrated
> in the wiki or not.
>
> > I would propose XML hosted on SVN. Although the learning curve would
> > be a bit stepper than with e.g. wiki markup it would give us the
> >  maximum flexibilty and a guaranteed future.
>
> I'm afraid that the learning curve is too high - lessons for lizards
> unfortunately gave you/us that lesson...

Sorry, but I never understood the "XML is too difficult" rant. People are
*not* afraid to learn LaTeX or Wiki, dig into HTML, or even migrate from
Windows to Linux because of "the learning curve is too high". Why they are not
afraid? Because they are _interested_ and want to _learn_ something new.

Why should it be difficult to learn DocBook/Novdoc? It's just a format as
HTML, WikiText, ASCIIDoc, or anything else. Maybe it's a bit more verbose, but
if you can write HTML and design your webpage, you can also write
documentation in DocBook or Novdoc. It's just a matter of your XML editor.

Of course, Lessons for Lizards was not as successful as we wished it would be.
However, it's a bit too easy to blame only XML for the demise. Maybe it had an
effect, maybe not. The biggest problem IMHO was time and marketing.


> I don't know if the learning curve was the only problem there, but at
> least it's "I have to learn another thing before I can contribute".

I'm afraid, I have to disagree here. "To learn another thing before I can
contribute" is the case for _every_ open source project. If you want to
contribute, you usually use what's there. If you are interested enough then
you are willing to take that "extra step". If not, you simply don't
contribute.

Just think of this example: People were not afraid to learn CVS. After some
time, it was more or less replaced by Subversion. Although it was not that
different, people were willing to learn the differences. Now it seems Git will
be the sucessor for Subversion. And *that* is really different from
CVS/Subversion! And what's the opinion? "Git is soo coool!" is what can I
heare a lot. ;)

 
> > Whatsmore, the existing documentation (speaking of almost
> > 2000 pages!!) already uses XML.
>
> OK, _that_ is an argument. But as you already wrote, it shouldn't be
> hard to convert it to wikitext.

Indeed, there are stylesheets (I've wrote it), but I wouldn't want to
transform a complete book. The two systems are too different in some aspects.


> And it would be a good testbed for the
> wikitext to XML converter - ideally there should be no difference after
> converting it forth and back again ;-) (and that would make us better
> than google translator *g*)
>
> [...]

Let me suggest another idea:
In my opinion, most people have problems with XML because it's (a) too
verbose, (b) it's too "complicated", and (c) you don't see the result. At
least that's what I hear a lot.

As most of the functionality thesedays goes through the Web, why not have a
XML editor in, let's say, Firefox?

Of course, it should offer the usual features but would hide the XML syntax
and display just the rendered text. I know, this is day-dreaming and the idea
is not new. However, I think, this would lower the entrance. We could use the
existing XML source without converting it to Wiki while embracing Web
usability. I think, this should solve the above problems.

Maybe we could use Bitflux, see http://bitfluxeditor.org/.



> [...]
> I see the public SVN as a fast solution so that people have a chance to
> dig into the manual's source. It might even be read-only in the
> beginning - having to upload patches to bugzilla or send them to the
> -doc mailinglist is still easier than reporting "on page 123 in section
> 'foo', there's a typo in 'baar'".

A page number is a bad choice as it can change easily. Better use the section
title or an anchor from HTML. :)

 
> But even if you give out SVN write access, I'm afraid that not many
> people will contribute to the XML source because of the learning curve.

What makes you so sure?

To cite Tim Berners-Lee:
»If you use the original World Wide Web program, you never see a URL or have
to deal with HTML. That was a surprise to me - that people were prepared to
painstakingly write HTML.«


> You have to "switch" from the rendered manual (HTML, PDF, ...) to the
> XML source, and you have to know at least some XML basics.

In Wikis you have to know some Wiki basics. What's the point here? :)

 
> OTOH the wiki is more like a long(er)-term solution, but makes
> contribution much easier - just click "Edit".

Sorry, I'm not convienced. DocBook exists for more than 10 years! It's well-
matured, very well documented, and it's one defacto standard for technical
documentation. Ok, maybe you can count DITA as well.

Although I'm not that much into the Wiki topic, I have the impression the Wiki
syntax is not very well "established":  One Wiki supports a certain syntax,
another don't. If this is really the case, I wouldn't call Wikis "a long-term
solution".

For easier contribution: See my idea above.

 
> Yes, writing a good wiki-to-XML tool will need some work, but it is
> possible. And it is worth the effort IMHO.

Why should we write some wiki-to-XML converter when we have already everything
in place, ready to be used?
 
 
> [...]
>
> You've seen the numbers from Rajko - around 90 active users in the last
> 3 months. That's still 89 more than in the "lessons for lizards" *g,d&r*

You compare apples with oranges. :)


--
Gruß/Regards,
    Thomas Schraitle

----------------------------------------------------------------------
SUSE LINUX Products GmbH   (o<   Documentation Specialist
Maxfeldstrasse 5           /\\  
90409 Nuernberg, Germany  _\_v   http://en.opensuse.org/Documentation_Team
SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg)
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

NetBeans/Eclipse Plugin for openSUSE Doc

Bryant, Christian
You know what would be nice, is if someone adept at Eclipse or NetBeans were to create a project template and plug-in for openSUSE NovDoc.  For instance, I created a project in NetBeans for a manual with everything I need to edit, but I'd need to do more configuration to run the make, too.  I wasn't using an IDE before but I started using NetBeans for some Ruby work and I can see the value in it for those not used to the command line.  If something like this already exists, please let me know - I'd love to poke it.  I suppose the equivalent already in my tool belt would be Texmaker or Kile.  A great feature would be to have real-time updates to the finished view in a separate pane as you save and run your make :)

Cheers,


Christian Bryant
http://en.opensuse.org/User:christian_bryant


IMPORTANT WARNING:  This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential.  You, the recipient, are obligated to maintain it in a safe, secure and confidential manner.  Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer.
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: NetBeans/Eclipse Plugin for openSUSE Doc

Kay Schenk-2


On 10/04/2010 08:41 AM, Bryant, Christian wrote:

> You know what would be nice, is if someone adept at Eclipse or
> NetBeans were to create a project template and plug-in for openSUSE
> NovDoc.  For instance, I created a project in NetBeans for a manual
> with everything I need to edit, but I'd need to do more configuration
> to run the make, too.  I wasn't using an IDE before but I started
> using NetBeans for some Ruby work and I can see the value in it for
> those not used to the command line.  If something like this already
> exists, please let me know - I'd love to poke it.  I suppose the
> equivalent already in my tool belt would be Texmaker or Kile.  A
> great feature would be to have real-time updates to the finished view
> in a separate pane as you save and run your make :)
>
> Cheers,
>
>
> Christian Bryant http://en.opensuse.org/User:christian_bryant

DANG! This WOULD BE brilliant! And yes, some things like DocBook have
been around for an eternity, but, really, I think the whole philosophy
of participating in ANY open source project should be to make things
easy enough for people to do it without, well, making them go through SO
much that is foreign to them!

Yep! We could certainly use something like this! :)

>
>
> IMPORTANT WARNING:  This email (and any attachments) is only intended
> for the use of the person or entity to which it is addressed, and may
> contain information that is privileged and confidential.  You, the
> recipient, are obligated to maintain it in a safe, secure and
> confidential manner.  Unauthorized redisclosure or failure to
> maintain confidentiality may subject you to federal and state
> penalties. If you are not the intended recipient, please immediately
> notify us by return email, and delete this message from your
> computer.

--
============================================================
Kay Schenk

"The trick is in what one emphasizes. We either make
 ourselves  miserable, or we make ourselves strong.
 The amount of work  is the same."
                                   -- Carlos Castaneda
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

RE: NetBeans/Eclipse Plugin for openSUSE Doc

Bryant, Christian
I should note there are two modules in the NetBeans trunk:

  org-netbeans-modules-docbook.nbm
  org-netbeans-modules-docbook-project.nbm

I tried to install them but they don't work (for me) at the moment - troubleshooting now.  I'm sure they don't address the larger recommendation below, but it's a starting point for the support question.  Many a page found Googling the modules and folks with the same question.

Cheers,

Christian Bryant

-----Original Message-----
From: Kay Schenk [mailto:[hidden email]]
Sent: Monday, October 04, 2010 8:55 AM
To: Bryant, Christian
Cc: [hidden email]
Subject: Re: [opensuse-doc] NetBeans/Eclipse Plugin for openSUSE Doc



On 10/04/2010 08:41 AM, Bryant, Christian wrote:

> You know what would be nice, is if someone adept at Eclipse or
> NetBeans were to create a project template and plug-in for openSUSE
> NovDoc.  For instance, I created a project in NetBeans for a manual
> with everything I need to edit, but I'd need to do more configuration
> to run the make, too.  I wasn't using an IDE before but I started
> using NetBeans for some Ruby work and I can see the value in it for
> those not used to the command line.  If something like this already
> exists, please let me know - I'd love to poke it.  I suppose the
> equivalent already in my tool belt would be Texmaker or Kile.  A
> great feature would be to have real-time updates to the finished view
> in a separate pane as you save and run your make :)
>
> Cheers,
>
>
> Christian Bryant http://en.opensuse.org/User:christian_bryant

DANG! This WOULD BE brilliant! And yes, some things like DocBook have
been around for an eternity, but, really, I think the whole philosophy
of participating in ANY open source project should be to make things
easy enough for people to do it without, well, making them go through SO
much that is foreign to them!

Yep! We could certainly use something like this! :)

>
>
> IMPORTANT WARNING:  This email (and any attachments) is only intended
> for the use of the person or entity to which it is addressed, and may
> contain information that is privileged and confidential.  You, the
> recipient, are obligated to maintain it in a safe, secure and
> confidential manner.  Unauthorized redisclosure or failure to
> maintain confidentiality may subject you to federal and state
> penalties. If you are not the intended recipient, please immediately
> notify us by return email, and delete this message from your
> computer.

--
============================================================
Kay Schenk

"The trick is in what one emphasizes. We either make
 ourselves  miserable, or we make ourselves strong.
 The amount of work  is the same."
                                   -- Carlos Castaneda

IMPORTANT WARNING:  This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential.  You, the recipient, are obligated to maintain it in a safe, secure and confidential manner.  Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer.
N�����r��y隊Z)z{.��hs맲��r��z�^�ˬz����uح��ڕ�&��ݱ隊Z)z{.��hs�^��)z{.��+�
Reply | Threaded
Open this post in threaded view
|

Re: [opensuse-marketing] The openSUSE Handbook proposal

Christian Boltz-5
In reply to this post by Thomas Schraitle-3
Hello,

on Montag, 4. Oktober 2010, Thomas Schraitle wrote:
> On Monday 04 October 2010 Christian Boltz wrote:
> > [...]
> >
> > I'm not sure about that. I don't say that it will be very easy, but
> > it should be possible, and it won't be too hard.
>
> You are underestimate the efforts.

We can make a shout match out of this ("No, I don't" ;-) - but I'd
prefer to use the time more productive.

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.

<written after otherwise completing the mail>
After googling around a bit (see linklist at the end of this mail) I
still tend to using the wiki because there are some (at least at the
first look) working converters available, while using bitflux would
maybe cause more work - it looks like the editor is only the frontend,
and the server-side handling would need to be written.

Another advantage of using the wiki as base would be that we can easily
create an "offline copy" of the wiki (for regions without useable
internet access) or of a set of pages (for example a build service
manual).
</written after otherwise completing the mail>

> > 90% of the formatting can be done with plain wikitext, and for the
> > remaining 10% templates can be used (which can, but don't have to
> > have a visible effect in the wiki). A "visible" template might be
> > something like "text printed on screen", an "invisible" template
> > might contain a keyword for the book index.
>
> We use a feature in DocBook/Novdoc what is called "profiling". We
>  label one paragraph for business related products and another one
>  for openSUSE products. When we process the manual, the paragraphs
>  are being "filtered" so only the requested product is visible in the
>  end format. Maybe this belongs to the remaining 10%...

That could use something like

    {{only_openSUSE|paragraph text}}  or  {{only_SLES|paragraph text}}

and the template would just be {{{1}}} to show the text and empty to
hide it.

Or, to make it a bit more flexible and to allow multiple targets without
duplicating the content, something like {{onlyIn|SLES,SLED|text}} could
be used in combination with ParserFunctions.

> > I think we could even develop a "XML skin" for mediawiki so that
> > the wiki can generate valid docbook/novdoc XML out of wiki pages
> > (with <para> instead of <p> etc.).
> > The alternative solution would be to post-process the wikitext or
> > the HTML to convert it to XML.
>
> Depending on the HTML this sounds scaring.

The advantage of the wiki is that it is _generated_ HTML (from
wikitext), so it won't be too scary ;-)

...
> > I'm afraid that the learning curve is too high - lessons for
> > lizards unfortunately gave you/us that lesson...
>
> Sorry, but I never understood the "XML is too difficult" rant. People
>  are *not* afraid to learn LaTeX or Wiki, dig into HTML, or even
>  migrate from Windows to Linux because of "the learning curve is too
>  high". Why they are not afraid? Because they are _interested_ and
>  want to _learn_ something new.

Or because they need it (for private usage or for the job) and _have to_
learn it.

> Why should it be difficult to learn DocBook/Novdoc? It's just a
>  format as HTML, WikiText, ASCIIDoc, or anything else. Maybe it's a
>  bit more verbose, but if you can write HTML and design your webpage,
>  you can also write documentation in DocBook or Novdoc. It's just a
>  matter of your XML editor.

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.

...
> > I don't know if the learning curve was the only problem there, but
> > at least it's "I have to learn another thing before I can
> > contribute".
>
> I'm afraid, I have to disagree here. "To learn another thing before I
>  can contribute" is the case for _every_ open source project. If you
>  want to contribute, you usually use what's there. If you are
>  interested enough then you are willing to take that "extra step".
>  If not, you simply don't contribute.

Thanks for confirming my two groups from above ;-) but I'd prefer not to
have that "extra step" so that everybody can contribute.

> Just think of this example: People were not afraid to learn CVS.
>  After some time, it was more or less replaced by Subversion.
>  Although it was not that different, people were willing to learn the
>  differences.

I think many users could just do
    alias cvs=svn
and continue as usual ;-) because the features most people use (co, up,
diff, commit) are basically the same.

>  Now it seems Git will be the sucessor for Subversion.
>  And *that* is really different from CVS/Subversion! And what's the
>  opinion? "Git is soo coool!" is what can I heare a lot. ;)

Again, this depends on your usage and needs. I know that Git has lots of
features, but IMHO that makes it also complicated when compared to SVN.

Personally I'd say I know SVN quite well, but don't really know Git
because I didn't really need it until now. The good thing is that at
least the checkout/clone is quite easy (and copy&paste-ready available
on most project homepages) - without knowing all details of Git, I can
still send a patch or post it in the bugtracker.

Developers who use Git in their daily work will of course know it better
and just ask the upstream developers to pick their changes from their
private Git repo.

Back to the manual: the question is if we need another tool which every
contributor has to learn (XML), or if we can use an existing one (wiki).

> Let me suggest another idea:
> In my opinion, most people have problems with XML because it's (a)
>  too verbose, (b) it's too "complicated", and (c) you don't see the
>  result. At least that's what I hear a lot.

Yes, that sums up the problem quite good.

> As most of the functionality thesedays goes through the Web, why not
>  have a XML editor in, let's say, Firefox?
>
> Of course, it should offer the usual features but would hide the XML
>  syntax and display just the rendered text. I know, this is
>  day-dreaming and the idea is not new. However, I think, this would
>  lower the entrance. We could use the existing XML source without
>  converting it to Wiki while embracing Web usability. I think, this
>  should solve the above problems.

Indeed, this sounds like a very good idea.

Since we are already dreaming: the HTML version of the manual should
have an "[Edit]" link attached to every section ;-)

We would also need an easy way to create a new chapter, but that has
lower priority because it isn't needed too often compared to fixing
errors or adding some details in the existing chapters.

If it works as expected, it would be a good solution that would make
contribution easy (that's the main problem with the current manuals).

> Maybe we could use Bitflux, see http://bitfluxeditor.org/.

The description on the homepage looks promising. Unfortunately the demo
seems to be broken (lots of "not found" errors for the JS files)...

> > [...]
> > I see the public SVN as a fast solution so that people have a
> > chance to dig into the manual's source. It might even be read-only
> > in the beginning - having to upload patches to bugzilla or send
> > them to the -doc mailinglist is still easier than reporting "on
> > page 123 in section 'foo', there's a typo in 'baar'".
>
> A page number is a bad choice as it can change easily. Better use the
>  section title or an anchor from HTML. :)

I was more thinking of PDF or printed manuals in this case ;-)

BTW: I think Jana Jaeger can tell you a story about printed manuals and
paperclips. hint: bug 65000 *g*

> > You have to "switch" from the rendered manual (HTML, PDF, ...) to
> > the XML source, and you have to know at least some XML basics.
>
> In Wikis you have to know some Wiki basics. What's the point here? :)

I see several points:
- the wiki has a "preview" button where you can see your changes. That's
  not WYSIWYG, but not too far away
- lots of people know wiki basics (think of all the people that write in
  wikipedia)
- and even if you don't know wiki syntax, I'd say it is very easy to
  understand - for example, a paragraph is just, well, a paragraph.

More important (and missed in your question) is the "switch" from the
rendered manual to XML source. Finding the correct place to edit in the
XML can be more difficult than doing the actual text change.
That's where the wiki is really good with an "[Edit]" link at every
section.

> > OTOH the wiki is more like a long(er)-term solution, but makes
> > contribution much easier - just click "Edit".
...
> Although I'm not that much into the Wiki topic, I have the impression
>  the Wiki syntax is not very well "established":  One Wiki supports a
>  certain syntax, another don't. If this is really the case, I
>  wouldn't call Wikis "a long-term solution".

Yes, there is indeed some wiki software with slightly different syntax.
I don't really see a problem in that because the software we use
(Mediawiki) has a well-defined syntax and is broadly used (wikipedia).

BTW: HTML and CSS have a similar "problem" - some browsers understand
additional tags or even misinterpret some tags. Does this mean nobody
uses HTML? ;-)

> For easier contribution: See my idea above.

Indeed, an online editor for the manual would be a very good idea.

The main reasons why I proposed using the wiki are:
- the "[Edit]" link - that makes finding the correct place for an edit
  easy (no need for grep, searching in the file etc.)
- already well-known or at least very easy to learn syntax
- result visible instantly

When I wrote my proposal, I wasn't aware of Bitflux, and therefore the
wiki was the tool that fulfilled the above requirements best.
If Bitflux can do all that and additionally keep the XML format, then it
might even be better than using the wiki.

> > Yes, writing a good wiki-to-XML tool will need some work, but it is
> > possible. And it is worth the effort IMHO.
>
> Why should we write some wiki-to-XML converter when we have already
>  everything in place, ready to be used?

To make it easier for contributors. But see above...

Let me paste some links that might be useful for the discussion and/or
technical implementation. Note that I just had a quick look at the
following pages.

https://wiki.ubuntu.com/DocBookWeb  and
http://fedoraproject.org/wiki/Converting_wiki_to_DocBook_XML
overview on several tools for wiki -> docbook
(seems openSUSE is not the only project that has a need for this)

http://code.google.com/p/gwtwiki/wiki/Mediawiki2Docbook
looks like working code, page mentions "partial working", so the
converter might need finetuning

http://www.mediawiki.org/wiki/Extension:XML_Bridge
http://www.mediawiki.org/wiki/Extension:Collection
Mediawiki extensions for docbook export

http://toolserver.org/~magnus/wiki2xml/w2x.php
online converter for wikitext -> docbook (and other formats), source
available

http://doc-book.sourceforge.net/homepage/
a wiki working with docbook format internally

http://www.tldp.org/wt2db/
command-line wikitext -> docbook converter


And now to the fun part:

> You compare apples with oranges. :)

Why not? Both are round, and you can eat both of them ;-))


Regards,

Christian Boltz
--
Lies halt mal dclp.*, da faellt dir nix mehr ein.  Wenn man ein
Guerteltier ueber die Tastatur abrollt, kommt besserer PHP Code
raus als da gepostet wird.              [R. Huebenthal in darw]
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Re: [opensuse-marketing] The openSUSE Handbook proposal

Karl Eichwalder
Hi Christian,

most of your arguments are not invalid ;)  Nevertheless are we
discussing writing manuals (books with more than some 100 pages) or just
a bunch of Web pages (in older times: SDB articles)?  Both have their
merits.

If it is about writing books, I do not buy your arguing about just
fixing a typo after pressing the "Edit" button, because up til now most
PDFs lack such a feedback button (would be a nice feature, though).

Even today, you can read the PDF with okular and make annotations that
you are free to submit as improvement feedback to the doc writers.  If
you want to contribute, there is no need to learn XML.  OTOH, learning
XML would not hurt ;)

XML usually is easy.  A paragraph is just surrounded by a <para> element
and it does not matter whether you append an empty line or not.  Ever
tried to edit an average wiki table?  Wiki table are just the rebirth of
SGML (shortref and usemap features in combination with omittag: see
http://books.google.de/books?id=OyJHFJsnh10C&pg=PA62&lpg=PA62&dq=sgml+shortref&source=bl&ots=DFr_Adu5eE&sig=DtHug1N95vmPDIodnZ0ZFyt5cVM&hl=en&ei=iyWsTMqAM5ac4AbY0ISWCA&sa=X&oi=book_result&ct=result&resnum=10&ved=0CDkQ6AEwCQ#v=onepage&q=sgml%20shortref&f=false
--if the link is too long, just click this one:

http://books.google.de/books?id=OyJHFJsnh10C&pg=PA62 ).

Conclusion: Writing books is as it ever was--if you learned your lesson,
it is easy, if you did not, either the reader will have a hard time or
you will need a good editor...

--
Karl Eichwalder
R&D / Documentation

SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg)
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

FW: [opensuse-marketing] The openSUSE Handbook proposal

Bryant, Christian
In reply to this post by Frank Sundermeyer
Think this should actually have been sent to this list :)

- Christian Bryant

-----Original Message-----
From: Bryant, Christian [mailto:[hidden email]]
Sent: Wednesday, October 06, 2010 8:57 AM
To: [hidden email]
Cc: 'Klaas Freitag'
Subject: RE: [opensuse-marketing] The openSUSE Handbook proposal

Just as a proof-of-concept for document writing community success, see http://flossmanuals.net - easy to use, produces nice output, has a great community of contributors.  In terms of wiki-to-book, Wikipedia has had that for some time, and there are some nice examples out there: http://en.wikipedia.org/wiki/Help:Books I'm sure there is a way to build on that model for openSUSE.

I have both the "good-writer-skill" and "I-like-to-fiddle-with-tools-which-produce-great-outcome", as Klaas puts it.  But I also have to recognize which one of these others are as well, as a project manager or in a community leader roll.  It's the users that should define what is pursued here, I believe.  I think the wiki-to-book functionality should definitely be added to the openSUSE wiki as an option, and if it matured to a point where all the other features discussed in this thread could be produced, then all the better.  For now, I am still using Emacs to edit my openSUSE documents - but the older I get, the simpler I like things to be :)  I wouldn't turn away from a nice wiki that would squirt out a publish-ready document!

Cheers,

Christian Bryant

>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


IMPORTANT WARNING:  This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential.  You, the recipient, are obligated to maintain it in a safe, secure and confidential manner.  Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer.
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


IMPORTANT WARNING:  This email (and any attachments) is only intended for the use of the person or entity to which it is addressed, and may contain information that is privileged and confidential.  You, the recipient, are obligated to maintain it in a safe, secure and confidential manner.  Unauthorized redisclosure or failure to maintain confidentiality may subject you to federal and state penalties. If you are not the intended recipient, please immediately notify us by return email, and delete this message from your computer.
--
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]