Mailinglist Archive: opensuse-project (72 mails)

< Previous Next >
Re: [opensuse-project] Google's Season of Docs
On 14/3/19 8:53 pm, Simon Lees wrote:


On 14/03/2019 20:03, Sarah Julia Kriesch wrote:


Gesendet: Donnerstag, 14. März 2019 um 10:06 Uhr
Von: "Simon Lees" <sflees@xxxxxxx>
An: opensuse-project@xxxxxxxxxxxx
Betreff: Re: [opensuse-project] Google's Season of Docs



On 14/03/2019 18:32, Sarah Julia Kriesch wrote:


Gesendet: Donnerstag, 14. März 2019 um 03:35 Uhr
Von: "Lana Brindley" <lbrindley@xxxxxxx>
An: opensuse-project@xxxxxxxxxxxx
Betreff: Re: [opensuse-project] Google's Season of Docs


Most of openSUSE's current documentation is generated along side SUSE's
so talking to SUSE's documentation team is probably the best starting
point. As a result of this if you look at https://doc.opensuse.org/ it
tends to cover things that are in SLE very well but doesn't tend to
cover areas outside that,

Yeah, the problem I see is that there is no community-based team for
these docs, the community is just relying on a re-badging of the
corporate docs.

for example there's a bunch of low hanging fruit in things like the
Gnome User Guide could probably be extended to other desktops like KDE
and there are probably a bunch of other features / things that we ship
in openSUSE that aren't in SLE that could equally make there way into
openSUSE's version of the documentation.

A content audit seems like a good place to start.


Since there's no mailing list or IRC any more, it's a little hard to know
how to go about building up a community around docs. Do you think this is
the best list to try and kick that off, or is there a more appropriate
place?


Given there seems to be interest you can ask the hero's nicely to create
a new mailing list or reactivate the old one (I don't know which is
easier) we only closed the old one due to inactivity.

Such a team exists. We had many questions on our wiki mailing list in the
past how to contribute to the real documentation of openSUSE, because this
documentation is only editable by the SUSE documentation team.

The community is only allowed to edit the wiki and that is the
documentation by the community at the moment.

This is maybe less true now, all the documentation has been open sourced
and is on github, although it's currently in SUSE's github which has
traditionally meant that SUSE isn't really expecting external
contributions. But still it is technically possible to create a pull
request. But really it would be best to discuss the best way forward
with the documentation team, they maybe willing and happy to accept pull
requests as is they may also be completely unprepared and not have the
man power to review a significant number of pull requests. Maybe it
makes sense to do the work in some other "New openSUSE feature branch",
at worst its possible to fork the documentation into openSUSE's github
and work on new areas of the documentation there still using SUSE's
templates and methods for building the docs. There might be other ways
as well, but the best people to work that through with is SUSE's
documentation team. They are friendly people i've met a bunch of them
over breakfast at some point.

We know about the friendliness. 2 years ago we should receive 1 guy for the
integration of openSUSE Contributions
and a better cooperation between the SUSE Documentation Team and our wiki
team. In addition, this guy should be allowed
to contribute to our wiki improvement during the working time. We had a
small discussion on our wiki mailing list that
the technology behind doc.opensuse.org was difficult to understand for
openSUSE newbies (without SUSE background). Therefore,
SUSE wants to be responsible for doc.opensuse.org.
We didn't watch any Contributions in  the wiki by the special SUSE
Documentation Team Member. We tried the integration,
but that was not possible.
Well a large amount can change in two years and it might be that the
people looking at it this time are willing to figure out the current
documentation system, especially if they have past experience in
documentation its probably what they are used to. From a quick glance its
mostly xml pretty similar to other documentation systems i've used in the
past. I'd be more then comfortable contributing a basic fix and I haven't
touched doco for years so i'm sure people who do it more regularly will pick
it up pretty easily.

So I wouldn't say its not worth trying again just because of past experiences
especially if there are people familiar with documentation that are willing
to train other people which is the whole point of Google's Season of Docs
anyway.

Yeah, I'm very familiar with Docbook XML (less so daps), but it is very much a
tech writer's toolchain. In my experience with upstream communities, switching
to a markdown language can greatly improve contributions from non-tech writers.
That's not to say that developers can't work it out (I'm positive they can),
but more about reducing the cognitive burden of doing so. This is something I
will discuss with the internal docs team.

Lana

--
Lana Brindley
Technical Writer - SUSE Manager

"The question is," said Alice, "whether you
can make words mean so many different things."

--
To unsubscribe, e-mail: opensuse-project+unsubscribe@xxxxxxxxxxxx
To contact the owner, email: opensuse-project+owner@xxxxxxxxxxxx

< Previous Next >