Re: [opensuse-wiki] Why is this acceptable?

On Fri, Jan 20, 2017 at 12:48 AM, Christoph Wickert <cwickert@suse.de> wrote:
> On Thu, 19 Jan 2017 16:49:56 -0800
> PatrickD Garvey <patrickdgarveyt@gmail.com> wrote:
>
>> On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <cwickert@suse.de>
>> wrote:
>> > On Wed, 18 Jan 2017 15:23:29 -0800
>> > PatrickD Garvey <patrickdgarveyt@gmail.com> 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@suse.de>
> 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@opensuse.org
To contact the owner, e-mail: opensuse-wiki+owner@opensuse.org