Why is this acceptable?

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

Re: Why is this acceptable?

Christian Boltz-5
Hello,

Am Dienstag, 3. Januar 2017, 16:40:14 CET schrieb Carlos E. R.:

> On 2016-12-31 17:53, Sarah Julia Kriesch wrote:
> >> Me, I find writing on the wiki a bit cumbersome, but it is an easy
> >> access place for both writers and readers.
> >
> > Can you describe what "a bit cumbersome" is?
> > You can fix only issues, if you know the problem.
>
> No, there is no way to repair that, it is by design of a "wiki"
> system. For instance, it is not WYSIWYG.
>
> One has to know "keywords" that should result in a certain format,
> then ask the system to produce the output and see the result. If it
> is not as wanted, change and repeat procedure.

Time for a funny story ;-)

I'm admin on two wikis for gardeners and wine growers. When I set up
those wikis, I showed them a WYSIWYG editor that (back then) worked with
MediaWiki.

After some testing, the surprising result was that they prefer to edit
wiki source, and IIRC the reason was because "it's easier". Yes, really!

This makes the wish for a WYSIWYG editor for the openSUSE wiki (which is
edited by people who much more "computer stuff" than a typical gardener)
somewhat funny ;-)


If there is really a demand for a WYSIWYG editor, I can of course check
what's available, if it fits our needs and doesn't get in the way of
people who prefer to edit wiki source. (From a quick look,
https://www.mediawiki.org/wiki/VisualEditor might be a good candidate.)

However, can we please do this after the wiki migration and update is
done? I already had some fun with all the extensions we use [1], and
updating everything to a new version already gives enough chances to
break something. Therefore I'd prefer not to add another extension to
the mix to avoid delays ;-)


Regards,

Christian Boltz

PS: To avoid another mail about the "Mr./Ms." - well, it depends ;-)
    If you write to someone the first time, using "Mr./Ms." is not really
    bad, and nobody will hate you for that. Maybe that person just
    thinks you are a bit too formal and/or not too familiar with the
    open source community.
    But if you always used the first name and suddenly switch to "Mr./
    Ms.", well... ;-)

[1] To keep the "This page has been accessed NNNN times." footer [2], I
    had to fix another extension. Migrating the openSUSE theme to the
    latest MediaWiki also was a funny[tm] task ;-)

[2] This feature is no longer part of MediaWiki and now available as the
    HitCounters extension.

--
Kann bitte jemand ein "Dumme Ideen Limit" für Politiker einführen?
1 dumme Idee pro Jahr klingt gut. Dann is Öttinger bis an sein
Lebensende nämlich ruhig, da er seinen Vorat schon verbraucht hat...
[Michael Schlesiger zu
https://plus.google.com/+KristianKöhntopp/posts/LMX1JWg6DfS]

--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Carlos E. R.-2
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 2017-01-03 18:39, Christian Boltz wrote:
> Am Dienstag, 3. Januar 2017, 16:40:14 CET schrieb Carlos E. R.:


>>> Can you describe what "a bit cumbersome" is? You can fix only
>>> issues, if you know the problem.
>>
>> No, there is no way to repair that, it is by design of a "wiki"
>> system. For instance, it is not WYSIWYG.
>>
>> One has to know "keywords" that should result in a certain
>> format, then ask the system to produce the output and see the
>> result. If it is not as wanted, change and repeat procedure.
>
> Time for a funny story ;-)
>
> I'm admin on two wikis for gardeners and wine growers. When I set
> up those wikis, I showed them a WYSIWYG editor that (back then)
> worked with MediaWiki.
>
> After some testing, the surprising result was that they prefer to
> edit wiki source, and IIRC the reason was because "it's easier".
> Yes, really!
>
> This makes the wish for a WYSIWYG editor for the openSUSE wiki
> (which is edited by people who much more "computer stuff" than a
> typical gardener) somewhat funny ;-)

Understandable :-)

Yet most of us use L.Office Writer ;-)

In the past I used editors that would switch view mode (tokens or
graphic) with a keypress. Both modes are useful. But an online editor
is typically also slow to react.

That said, my preferred tool is LyX.


> If there is really a demand for a WYSIWYG editor, I can of course
> check what's available, if it fits our needs and doesn't get in the
> way of people who prefer to edit wiki source. (From a quick look,
> https://www.mediawiki.org/wiki/VisualEditor might be a good
> candidate.)
>
> However, can we please do this after the wiki migration and update
> is done? I already had some fun with all the extensions we use [1],
> and updating everything to a new version already gives enough
> chances to break something. Therefore I'd prefer not to add another
> extension to the mix to avoid delays ;-)

Yes, of course. I'm not in any hurry either, and I write very few wiki
pages, so don't base decisions on me alone.


>

>
> PS: To avoid another mail about the "Mr./Ms." - well, it depends
> ;-) If you write to someone the first time, using "Mr./Ms." is not
> really bad, and nobody will hate you for that. Maybe that person
> just thinks you are a bit too formal and/or not too familiar with
> the open source community. But if you always used the first name
> and suddenly switch to "Mr./ Ms.", well... ;-)

Oh :-(

Then somebody may be a bit pissed at me for that reason, unbeknown to
me. :-(

- --
Cheers / Saludos,

                Carlos E. R.

  (from 13.1 x86_64 "Bottle" (Minas Tirith))
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iF4EAREIAAYFAlhr7FkACgkQja8UbcUWM1z+pgEAl5yEu+gvdTiVQp2eOxq/XkXW
KlEQJUufSPy7lSlxjTAA/1gL7S9Pq7IHGCsizeYlhN9JV/nb0O+R889NIYdGF1n3
=wJPH
-----END PGP SIGNATURE-----
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Christoph Wickert
In reply to this post by Sarah Julia Kriesch
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" <[hidden email]> 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 <[hidden email]>
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)


attachment0 (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

PatrickD Garvey
On Tue, Jan 17, 2017 at 8:26 AM, Christoph Wickert <[hidden email]> wrote:

> 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" <[hidden email]> 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.
>

Please allow me to ask a question so I am clear as to what you are
saying about the SUSE documentation team.
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?
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Christoph Wickert
On Wed, 18 Jan 2017 15:23:29 -0800
PatrickD Garvey <[hidden email]> 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. If I worked as a kernel developer,
I had to write my code in C. This is not only a technical requirement
as the kernel is written in C, but also a tribute to the people who
actually wrote all that code over the last 25 years.

If I wanted to write in a different language, I would have to convince
people that my approach is superior. Given the size of the code and the
kernel community, this is going to be tough, so I would probably have
to start from scratch. If my project is successful, I can win people
over. I hear Google is working on an OS written in their Go language.
Let's see how that goes.

Back to documentation: If I wanted to use something else but DocBook, I
would have to convince my team, too. I know they are always open to
improvements, so once I manage to convince them, they would support me
and we would work on a migration path together.

The same goes for us. We are always grateful for suggestions and I don't
mind if they sound controversial. I will listen, provide feedback,
listen again, etc., before I make a decision. And then it's on all of
us to decide and reach consensus.

But at the end of the day we will not reach a consensus by talking but
by doing. The ones doing the work define the direction. If you write a
wiki page, you define the content. To me, that's the very essence of
Free Software: Nobody tells you what to do, you do what you do because
you want it to happen. openSUSE is a community of equals. It doesn't
matter if you are a volunteer or on SUSE's payroll, we all share the
same goal: Improve openSUSE. And we get recognition for what we do. We
lead by example and not by authority.

Back to your initial question of whether it is acceptable that some
information is moved from the wiki to GitHub. I think it is. First of
all, the information was not openSUSE-specific. If we want a project
like Icecream to succeed, it needs wide adoption, and this is better
achieved on GitHub than on some openSUSE infrastructure. (In fact, I
would like to see more projects that were started by SUSE employees or
openSUSE become independent of the company and distribution because it
allows participation from other people and communities. We have so many
awesome tools in openSUSE, but we don't talk about them enough.)

Last but not least it's not on us to decide where this documentation
resides, but on the people who write and maintain it. Coolo, who moved
the information, is also a developer of Icecream. As long as he gets the
job done, nobody is to tell him what to do. We should support
everything that makes it easier for him to get get his job done.

If we consider Icecream documentation useful for openSUSE users, we can
add it back to the wiki. In fact, you can just go ahead and do it,
nobody will stop you. On the contrary, people will be grateful. But we
should not just add and forget it. If none of us can make the
commitment to maintain the wiki page, we should just trust the upstream
developers. I think we all agree that a link to the recent version on
GitHub is better than outdated information in the wiki.

And this problem is not specific to the Icecream documentation. We
should think carefully about what information should be on the wiki and
what is better kept elsewhere. We should avoid duplication because we
will not only duplicate information but also work, making it harder for
both wiki editors and documentation writers to contribute. Instead, we
should focus on bringing the relevant bits together and making them
accessible to our users, e.g. through a smart search engine.

So in order to to decide what belongs where, there are a few
questions:
1. What is static and what keeps changing frequently?
2. What output formats do we need for a particular piece of information?
3. Where will our users find and use the information easily?
Once we have these questions answered, we can move ahead.

For me, the question is not "Why is this acceptable?" or "Is this
acceptable?" but "Is this feasible?". Does it help us to make the wiki
and openSUSE better? I will support everything that does and am looking
forward to your suggestions.

This call for feedback goes out to all of you wiki editors. Let me know
what is missing from the wiki or our documentation. What is good, what
needs to be improved? Just fire everything at me :) and I will see what
the SUSE documentation team can do to help.

Best regards,
Christoph

--
Christoph Wickert <[hidden email]>
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)


attachment0 (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

PatrickD Garvey
On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <[hidden email]> wrote:

> On Wed, 18 Jan 2017 15:23:29 -0800
> PatrickD Garvey <[hidden email]> 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?
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Christoph Wickert
On Thu, 19 Jan 2017 16:49:56 -0800
PatrickD Garvey <[hidden email]> wrote:

> On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <[hidden email]>
> wrote:
> > On Wed, 18 Jan 2017 15:23:29 -0800
> > PatrickD Garvey <[hidden email]> 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 <[hidden email]>
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)


attachment0 (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Carlos E. R.-2
On 2017-01-20 09:48, Christoph Wickert wrote:
> On Thu, 19 Jan 2017 16:49:56 -0800
> PatrickD Garvey <> wrote:


>> 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.
I have a curiosity.

How about using LyX? As I remember, it includes docbook support, and it
is WYMIWYG (what you mean is what you get). There is some visual
indication of how the document is going to look (not fully).

--
Cheers / Saludos,

                Carlos E. R.
                (from 42.2 x86_64 "Malachite" at Telcontar)


signature.asc (188 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Sarah Julia Kriesch
Hi Carlos,

> Gesendet: Freitag, 20. Januar 2017 um 12:02 Uhr
> Von: "Carlos E. R." <[hidden email]>
> An: [hidden email]
> Betreff: Re: [opensuse-wiki] Why is this acceptable?
>
> On 2017-01-20 09:48, Christoph Wickert wrote:
> > On Thu, 19 Jan 2017 16:49:56 -0800
> > PatrickD Garvey <> wrote:
>
>
> >> 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.
>
> I have a curiosity.
>
> How about using LyX? As I remember, it includes docbook support, and it
> is WYMIWYG (what you mean is what you get). There is some visual
> indication of how the document is going to look (not fully).
>
> --
> Cheers / Saludos,
>
> Carlos E. R.
Do you want to combine DocBook and wiki? Tell us about your reasons and background.
But it sounds for me like Christian's proposal with the wiki plugin: https://www.mediawiki.org/wiki/Talk:WYSIWYG_editor

Best regards,
Sarah
--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

DocBook editors (was: Why is this acceptable?)

Christoph Wickert
In reply to this post by Carlos E. R.-2
On Fri, 20 Jan 2017 12:02:06 +0100
"Carlos E. R." <[hidden email]> wrote:

> How about using LyX? As I remember, it includes docbook support, and
> it is WYMIWYG (what you mean is what you get). There is some visual
> indication of how the document is going to look (not fully).

Frankly speaking I have no experience with Lyx. AFAIK it more or less
usable, but not really "what you get" as all the editing happens in the
lyx format and only exports to DocBook. If you really want to
consistently get what you mean throughout all formats, you have to
stick to the source, that means to DocBook.

Also, I'm not sure if lyx supports custom schemas such as geekodoc, but
it's probably a good start for somebody who is not familiar with
DocBook. So if somebody wants to contribute to the SUSE/openSUSE
documentation and submits something as Lxy-generated DocBook, that's
perfectly fine. If it doesn't validate with our schema, a little sed
and awk magic should help.

Long story short: If you want to help us with the documentation and
have written something, any format should do. Throw plain text at us
and we will take care of the rest. We even had submissions from
partners as MS Word documents, so it can't get any worse than that. ;-)

Best regards,
Christoph

--
Christoph Wickert <[hidden email]>
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)


attachment0 (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Carlos E. R.-2
In reply to this post by Sarah Julia Kriesch
On 2017-01-20 17:03, Sarah Julia Kriesch wrote:
> Hi Carlos,


>> I have a curiosity.
>>
>> How about using LyX? As I remember, it includes docbook support, and it
>> is WYMIWYG (what you mean is what you get). There is some visual
>> indication of how the document is going to look (not fully).


> Do you want to combine DocBook and wiki? Tell us about your reasons and background.
> But it sounds for me like Christian's proposal with the wiki plugin: https://www.mediawiki.org/wiki/Talk:WYSIWYG_editor

Huh, no, I had not considered DocBook and wiki, no.

If Christian proposal works that will be interesting :-)


--
Cheers / Saludos,

                Carlos E. R.
                (from 42.2 x86_64 "Malachite" at Telcontar)


signature.asc (188 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: DocBook editors

Carlos E. R.-2
In reply to this post by Christoph Wickert
On 2017-01-20 18:08, Christoph Wickert wrote:

> On Fri, 20 Jan 2017 12:02:06 +0100
> "Carlos E. R." <[hidden email]> wrote:
>
>> How about using LyX? As I remember, it includes docbook support, and
>> it is WYMIWYG (what you mean is what you get). There is some visual
>> indication of how the document is going to look (not fully).
>
> Frankly speaking I have no experience with Lyx. AFAIK it more or less
> usable, but not really "what you get" as all the editing happens in the
> lyx format and only exports to DocBook. If you really want to
> consistently get what you mean throughout all formats, you have to
> stick to the source, that means to DocBook.
In any case, with LyX you have to compile or create the output format.
Normally it would be PDF, ps, html... In this case, there may an extra
step in generating xml.

The advantage of LyX is using a nice looking original that looks similar
to the expected output, before "compilation". Easier to start.
However... always something seems to fail.


>
> Also, I'm not sure if lyx supports custom schemas such as geekodoc, but
> it's probably a good start for somebody who is not familiar with
> DocBook. So if somebody wants to contribute to the SUSE/openSUSE
> documentation and submits something as Lxy-generated DocBook, that's
> perfectly fine. If it doesn't validate with our schema, a little sed
> and awk magic should help.

I asked because years ago I tried a go with LyX and docbook, and I did
not succeed. I wanted to try that method because I find the act of
editing or writing in LyX easy. My goal at the time was producing man
pages. Or rather translating them. I do not like having to edit and see
to tokens or xml in the text, too confusing for me.

I also tried with the older linuxdoc, and failed, too. The man page
stylesheet (or whatever is the proper name for LyX) was incomplete or bad.




> Long story short: If you want to help us with the documentation and
> have written something, any format should do. Throw plain text at us
> and we will take care of the rest. We even had submissions from
> partners as MS Word documents, so it can't get any worse than that. ;-)

Good to know :-)


No, I do not have anything to write about currently, not for
doc.opensuse. I'm just exploring possibilities. You people know more
about this than me, so I took the chance to ask ;-)

I do have pending work to do on the wiki, yes (the offline upgrade page).




--
Cheers / Saludos,

                Carlos E. R.
                (from 42.2 x86_64 "Malachite" at Telcontar)


signature.asc (188 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

PatrickD Garvey
In reply to this post by Christoph Wickert
On Fri, Jan 20, 2017 at 12:48 AM, Christoph Wickert <[hidden email]> wrote:

> On Thu, 19 Jan 2017 16:49:56 -0800
> PatrickD Garvey <[hidden email]> wrote:
>
>> On Thu, Jan 19, 2017 at 9:38 AM, Christoph Wickert <[hidden email]>
>> wrote:
>> > On Wed, 18 Jan 2017 15:23:29 -0800
>> > PatrickD Garvey <[hidden email]> 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 <[hidden email]>
> 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: [hidden email]
To contact the owner, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Christoph Wickert
On Fri, 20 Jan 2017 15:10:03 -0800
PatrickD Garvey <[hidden email]> wrote:

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

Hi Patrick,

no problem, you–and all the others–are welcome.

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

Sorry, my bad. Even though I wrote "all this", I meant to refer only to
the wiki maintenance guidelines because I assumed people on this list
know them. I was not referring to all the other stuff I wrote and which
is probably new to everybody but me. That's why explain it in great
detail. If somebody has any questions, please don't hesitate to ask.

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

That's a very noble goal, that I can wholeheartedly support. As someone
who has been around in the Fedora community for over a decade, I still
find many things about openSUSE confusing. Getting new contributors
onboarded quickly is definitely something we should focus on when we
improve the wiki.

Something like a "New Contributors Guide" would be pretty cool to have.
Anybody (with more experience than me) wants to work on that? I would
offer being the guinea pig and ask all the questions newbies have. ;-)

Best regards,
Christoph

--
Christoph Wickert <[hidden email]>
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)


attachment0 (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Why is this acceptable?

Christian Boltz-5
Hello,

Am Mittwoch, 25. Januar 2017, 14:10:16 CET schrieb Christoph Wickert:
> That's a very noble goal, that I can wholeheartedly support. As
> someone who has been around in the Fedora community for over a
> decade, I still find many things about openSUSE confusing.

Can you please list these confusing things?
I'm probably routine-blinded and don't notice them anymore ;-) [1]

> Getting
> new contributors onboarded quickly is definitely something we should
> focus on when we improve the wiki.
>
> Something like a "New Contributors Guide" would be pretty cool to
> have. Anybody (with more experience than me) wants to work on that? I
> would offer being the guinea pig and ask all the questions newbies
> have. ;-)

Wrong attemp - someone with more experience can't write such a guide ;-)

I'd write the "New Contributors Guide" in one sentence - "just do it!".
While this is IMHO the most important thing to learn in openSUSE
(actually in any open source project), it probably isn't too helpful for
new contributors. Again, I'm probably routine-blinded ;-)

Therefore I'd propose that _you_ start to write this guide. You already
have a bit of experience, but are not as routine-blinded as I might be,
and probably remember which of your first steps were most difficult.
Also, while writing the guide, you'll find out which questions are easy
to answer (so you just need to link to the respective wiki page etc.)
and which are hard to answer (which means missing or hard to find
information).

If you can't answer a question yourself, feel free to ask on the
mailinglist. I'll also be available to proofread if whatever you write
makes sense or if it needs adjustments. So - did I already mention that
you should "just do it" without being afraid of mistakes? [2]


Regards,

Christian Boltz

[1] Just to give you an idea - I use SuSE Linux since 7.3 (IIRC), and
    became a betatester in 9.2 after asking and answering too many
    questions on the suse-linux (nowadays opensuse-de) mailinglist.

[2] Mistakes are a good thing because you learn something from them ;-)

--
>> I can do better things with my life and free time then to just scroll
>> up and down on a mailing list.
> Come on, let's not be childish!
That's where the children come from: scrolling up and down with your
wife. [>> houghi, > Christoph Thiel and Eberhard Moenkeberg in opensuse]

--
To unsubscribe, e-mail: [hidden email]
To contact the owner, e-mail: [hidden email]

12