Mailinglist Archive: opensuse-wiki (26 mails)

< Previous Next >
Re: [opensuse-wiki] Why is this acceptable?
  • From: "Sarah Julia Kriesch" <ada.lovelace@xxxxxx>
  • Date: Tue, 3 Jan 2017 16:36:21 +0100
  • Message-id: <trinity-9ffef069-7c08-48a5-9ebe-ce47015aacb2-1483457781806@3capp-gmx-bs47>


Gesendet: Montag, 02. Januar 2017 um 14:35 Uhr
Von: "Ancor Gonzalez Sosa" <ancor@xxxxxxx>
An: opensuse-wiki@xxxxxxxxxxxx
Betreff: Re: [opensuse-wiki] Why is this acceptable?

On 12/31/2016 01:51 PM, Sarah Julia Kriesch wrote:

Gesendet: Freitag, 30. Dezember 2016 um 23:00 Uhr
Von: "Carlos E. R." <robin.listas@xxxxxxxxxxxxxx>
An: opensuse-wiki@xxxxxxxxxxxx
Betreff: Re: [opensuse-wiki] Why is this acceptable?

On 2016-12-30 19:34, PatrickD Garvey wrote:
On Fri, Dec 30, 2016 at 3:12 AM, Sarah Julia Kriesch <> wrote:


Sarah,
To put my response to your reply succinctly, you're not seeing the
world through my eyes.

As I understand it, your perception of the variety of tools used to
accomplish the tasks required to support the openSUSE project and the
SUSE product is an opportunity to learn many things. My perception is
each learning opportunity is a use of time that is needed to produce
the components of the project/product that is non-productive if one
has already learned a tool and it's syntax that does the job.

Learning a second, third, fourth, fifth, sixth, seventh, ...
documentation tool is non-productive when my objective is to provide
high quality documentation. The fact there are three different
syntax's that are used by three different documentation producing
sub-communities also increases the effort required to coordinate the
work of those sub-communities such that the same documentation is
produced only once, not three times. The fact there is a link in the
openSUSE wiki to a GitHub file indicates it takes an unnecessary
expenditure of time for a new member of the openSUSE project just to
locate the documentation, let alone keep it up to date.

Producing software products is still a very labor-intensive process.
Diverting available time to repeated re-learning of a mastered skill
is a serious cost to the quality, as well as the quantity, of the
output.

With my user and tech writer hat on, I agree.

--
Cheers / Saludos,

Carlos E. R.
Thanks for your feedback!

You read the view of a Software Developer by Ancor (YaST Developer at
SUSE), too.
@Ancor: Thanks that you answered the question with Github of the view of
somebody in the Development at SUSE. :-)

Open Source Developers are using Github and write their documentation
there. Ancor and the YaST Team are doing that for YaST here:
http://yast.github.io/documentation

Well, in fact we are using Github for the developer-oriented
documentation and keeping the wiki for the user-oriented documentation.

In my original mail I already explained why Github is the right place to
reach potential developers. And it's not realistic to expect translated
documentation for developers (they will have to communicate in English
to get the patches accepted anyways). That's why we decided it was fine
to leave the rather inconvenient (for our purposes) wiki behind. But
just for developer doc.

We don't plan to move the user documentation because we see the
strengths of the wiki for that (it's a known central place, it's known
by our community of translators, etc.).

I would not move anything. I think about using plugins or anything else for
copying content automatically after hearing all meanings. But I wouldn't do
anything without a permit!
I was surprised about the "too many tools" at first and after that Patrick
wants to use Gitlab, because Github is public.
I can understand the first meaning of a beginner at openSUSE. The second point
isn't consequentally to the first point.

The normal user (user of openSUSE) wants to use a wiki of their Linux
distribution. That can give the best overview about the operating system.
We (wiki Team) are responsible for updating it. We don't have many
Developers on the mailing list.
That was the reason for linking the Github documentation on the wiki page.
It is difficult to get a Developer for writing his documentation on both
portals (Github and wiki). They have got the same meaning like you as a
Technical Writer. They want to use one platform and commit their code and
documentation on one way.

If you want them to use any platform different than Markdown files at
Github, you have to make sure the extra effort pays off for them.

Christian and I setup a new wiki at the moment. I can bring this topic into our
Heroes Meeting this Sunday, if we get an answer by the Documentation Team this
week and I can summarize/ evaluate something for that.

I have got the view of a System Administrator: I want to have happy
cumstomers and developers!
What can I do for having both? I view the work of developers on Github/
mailing list/ release notes until now and updated the wiki. I live freedom,
that everybody can contribute where he likes.

One Slogan I learned in my first job: "Happy cows give better milk!" Is the
cow more happy while running free or being locked-in?
You can transfer it to an open source project:
-> Happy Developers (with freedom) develop better software.
-> Happy System Administrators (with freedom) make better system
administration.
-> Happy Technical Writers (with freedom) write better documentations.

Now we have got the questions, why we have got a third documentation tool.
This tool can create a completely documentation in pdf. Some customers want
to have a printed or pdf version of a documentation. Every other
distrubtion has got it beside of their wiki, too. The Documentation Team at
SUSE is doing most parts of this job at the moment. We should ask Christoph
of this team after his view and meaning about documentations with different
tools.
@Christoph: How is your job with different tools (wiki/ doc/ Github)? Do
you have ideas for improvements?

I want to have meanings of all different views in our wiki team before
finding a solution. I want to have happy Contributors in our wiki Team. ;-)

And if we are talking about variety of tools, don't forget we have two
for translators: Weblate for translating software and the wiki for
translating... well, for translating the wiki.

Psst! :-)
We have got a separate mailing list for translators (with Weblate). Patrick
wants to work in the Technical Documentation (English) and 3 tools are too
much. We have to analyze the problem of Patrick and Carlos. We can add
features into our new wiki instance (if needed). But I want to hear all before
doing that. ;-)

Theoretically, Weblate is powerful enough to be used to translate
different sources, including a Wiki, stuff coming from Github, etc. But
that of course means that somebody needs to set the system.

Patrick doesn't want to translate...

Tools... the never-ending strength/weakness of the openSUSE project...

Enjoy the last hours of this year and have a happy new year!
Best regards,
Sarah

Happy new year.

--
Ancor González Sosa

I want to work based on the Software Development Life Cycle in all projects
(unimportant whether technical or not technical).
1. Planning: Asking all after their problems and summarizing that. Looking
after such processes in other teams or communities, whether something like that
exists.
2. Analysis: Defining the problem and finding solutions/ plugins...
3. Design: Evaluating of solutions on test systems. We have got a test system
at the moment. ;-)
4. Implementation/ Installation: Integration of the solution into our new wiki
setup.
5. Testing: Testing it and asking, whether all are happy. :-)
6. Maintenance: Improving, if something has to be improved.

Best regards,
Sarah
--
To unsubscribe, e-mail: opensuse-wiki+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: opensuse-wiki+owner@xxxxxxxxxxxx

< Previous Next >
List Navigation
References