Mailinglist Archive: opensuse-wiki (26 mails)

< Previous Next >
Re: [opensuse-wiki] Why is this acceptable?
Hello everybody,

sorry for chiming in so late. I have been really busy. :-(

On Sat, 31 Dec 2016 13:51:01 +0100
"Sarah Julia Kriesch" <ada.lovelace@xxxxxx> wrote:

@Christoph: How is your job with different tools (wiki/ doc/
Github)?

That is a huge question. :-) Let me start with a little bit of
background about the SUSE documentation team and our work.

Obviously, we write documentation. The language we use is DocBook XML.
There are alternatives such as AsciiDoc, reStructuredText, or Markdown.
They are probably easier to learn and we thought about a migration more
than once, but every time we decided to stick to DocBook because it is
the only language that provides all the necessary features and covers
all our use cases.

I could go into the technical details, but let me just point out the
main advantages of DocBook:

1. You can use XSLT stylesheets to convert DocBook into any output
format you want. DAPS, our "DocBook Authoring and Publishing Suite" [1],
currently supports HTML, PDF, plain text, man pages, epub, and mobi.

2. Stylesheets can also be used to apply a look or branding to the
documentation. The SUSE and openSUSE documentation is built from the
same sources and is (mostly) the same, but we use different stylesheets
to make them look different.

3. You can use conditionals and entities. Conditionals can be used
to include a something in say the SUSE documentation but not on
openSUSE. Entities are variables which are used to things like product
names, versions and alike. This allows us to share a large part of the
documentation between SUSE and openSUSE.

4. You can use schemas to limit the elements writers are allowed to
use. DocBook is huge and our stylesheets don't cover all the elements,
so we only use a subset called GeekoDoc [2].

As you can see our whole toolchain is open source and freely available,
starting from the source code on github [3] over the schemas [2] and
stylesheets [4] to the tools to check and [5] to generate [1] the
output. We also have two OBS repos with our tools, one for the stable
releases [6] and one for development [7]. Every openSUSE user can
contribute by sending pull requests [3].

Do you have ideas for improvements?

Frankly speaking I haven't yet thought about improvement much. I'm (more
of less) happy with the current process and tooling, but that's me with
my documentarian hat on. I can see why volunteers might see things
differently.

I think the important thing we need to keep in mind is that different
people have different needs. While the SUSE documentation team needs
something that can cater all output formats, somebody who only edits
the wiki probably does not care.

As you said "happy cows give better milk". For me this means we should
allow everybody to do their work the way that works best for them.
Unfortunately this also means that we end up with a variety of tools
and languages, but that's just the way it is. If you want to drive a
nail into a wall, you use a hammer and not a screwdriver. There is no
use telling people to use screwdrivers. And I'm afraid there is no
multi-tool either.

For example, we could easily export DocBook documentation to the
Wiki. There are already XSLT stylesheets for MediaWiki export. But I am
not sure we want that. Before we decide to do so, we should think about
two things:

1. What parts of the documentation should be in the wiki? A wiki is
best suited for frequently changing information, e.g. a list of known
bugs and workarounds. On the other hand, information that only changes
with every release or not at all, should probably remain on
docs.opensuse.org.

2. How would we handle feedback? One of the main advantages of the wiki
is the low entry barrier. It is easy to edit, in fact, we encourage
contributions and we are always looking for more feedback. So when we
export something to the wiki, and some community members improve it
there, how do we make sure this feedback is synced back to the
documentation on GitHub? If we don't incorporate the changes, they will
be overwritten by the next export and the volunteers are upset. If we
tell them to submit a pull request upstream on GitHub, they have to
learn yet another language and are probably upset, too.

Again, there are different target audiences with different use cases.
There is a reason why we have all these different tools and processes.
I can understand that for some people this seems a mess, but I see it
as diversity and a sign of a broad and active community.

I'm all for better collaboration. So if anybody has any questions or
suggestions about our tooling, I'm looking forward to hear them.

Best regards,
Christoph


[1] https://opensuse.github.io/daps/
[2] https://github.com/openSUSE/geekodoc/
[3] https://github.com/SUSE/doc-sle/
[4] https://github.com/openSUSE/suse-xsl/
[5] https://github.com/openSUSE/suse-doc-style-checker/
[6] https://build.opensuse.org/project/show/Documentation:Tools
[7] https://build.opensuse.org/project/show/Documentation:Tools:Develop


--
Christoph Wickert <cwickert@xxxxxxx>
Technical Writer
SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nürnberg
Tel: +49-911-74053-0; Fax: +49-911-7417755; https://www.suse.com/
SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard,
Graham Norton, HRB 21284 (AG Nürnberg)

< Previous Next >
List Navigation
Follow Ups