Mailinglist Archive: opensuse-wiki (26 mails)

< Previous Next >
Re: [opensuse-wiki] Why is this acceptable?
  • From: PatrickD Garvey <patrickdgarveyt@xxxxxxxxx>
  • Date: Fri, 20 Jan 2017 15:10:03 -0800
  • Message-id: <CAE-bVUmX9ZtG_EFxr6yW2sQK0MSRBdjmaiwp90iUvzLOpRf=WA@mail.gmail.com>
On Fri, Jan 20, 2017 at 12:48 AM, Christoph Wickert <cwickert@xxxxxxx> wrote:
On Thu, 19 Jan 2017 16:49:56 -0800
PatrickD Garvey <patrickdgarveyt@xxxxxxxxx> wrote:

On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <cwickert@xxxxxxx>
wrote:
On Wed, 18 Jan 2017 15:23:29 -0800
PatrickD Garvey <patrickdgarveyt@xxxxxxxxx> wrote:

When SUSE LLC hires a new member of the SUSE documentation team,
what documentation tool are they allowed to use to produce the SLES
documentation?

Hi Patrick,

we can to use any editor as long as it produces valid DocBook XML.
This allows us to have long discussions about the old topic of vim
vs. emacs :-) or just use Atom, gedit, or whatever.

However DocBook as language is set.

What is the new SUSE LLC employee provided to learn DocBook and the
SUSE LLC documentation team's style in using DocBook?

Hi Patrick,

that's a good question, because it reminds me of some resources I
forgot to mention earlier. :-(

Before I joined SUSE, I worked at Kolab Systems. The documentation for
the Kolab Groupware Server was (but no longer is) written in DocBook,
too. So I already knew some bits, but my knowledge was *very* limited.
After almost 10 months at SUSE, I still consider my DocBook skills
limited compared to my colleagues.

The first thing I was given to read when I joined SUSE was the DAPS
user guide [1]. I not only read it but provided feedback and fixed
errors I found during reading.

Next I read the SUSE Documentation Style Guide [2]. It's a collection
of Dos and Don'ts compiled by the SUSE documentation team. You don't
need to know it by heart, because there still is the style-checker
[3] that should catch the most common things from the style guide.

Neither at Kolab Systems nor at SUSE I received any DocBook training.
If you know XML, the DocBook structure is self-explaining. For the
elements, you need a reference such as "DocBook: The definitive
Guide" [4].

Just as there are plenty of resources for DocBook, there are resources
for MediaWiki [5]. For the openSUSE wiki, we have a set of Maintenance
Guidelines [6].

I'm sure you know all this already. I apologize for preaching to the
choir, the point I'm trying to make is the same as in my previous mail:
We should not duplicate information and work. We don't need
documentation for MediaWiki or DocBook, because it's already out there
on the web. We should focus on the openSUSE-specific bits such as the
documentation README [7], the style guide, and the wik maintenance
guidelines. We should work on improving documentation for new
contributors. Whatever they need to get going, we should provide it.

The SUSE documentation has a lot of experience with this. We are not
only responsible for the SUSE/openSUSE documentation but also for the
new hires documentation within SUSE. Just as I want every new colleague
to find their way into company, I want every volunteer to find their way
into the community. So if you can think of ways to improve the
onboarding experience for new contributors, just let us know and we
will look what we can do about it.

Best regards,
Christoph

P.S.: Again, this call for feedback goes out to all of you, not just to
Patrick. :-)


[1] https://opensuse.github.io/daps/doc/index.html
[2] https://doc.opensuse.org/documentation/styleguide/
[3] https://github.com/openSUSE/suse-doc-style-checker/
[4] http://tdg.docbook.org/
[5] https://www.mediawiki.org/wiki/Help:Contents
[6] https://en.opensuse.org/Help:Maintenance
[7] https://github.com/SUSE/doc-sle/blob/develop/README.adoc

--
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)


Thank you, Christoph, for your complete answers and your patience in
providing them.

You say, "I'm sure you know all this already." That's a bad working
assumption. It's good in that it means you respect my intelligence,
but it leaves me without the complete set of information you have
provided here.

I first became interested in openSUSE when I saw a presentation about
openQA at SCaLE 13x in 2015. I'm still, two years later, trying to
understand the project work flow. I would really like to shorten that
two years for those that come behind me.
--
To unsubscribe, e-mail: opensuse-wiki+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: opensuse-wiki+owner@xxxxxxxxxxxx

< Previous Next >
List Navigation
Follow Ups