Mailinglist Archive: opensuse-project (72 mails)

< Previous Next >
Re: [opensuse-project] Google's Season of Docs
On 19/03/2019 00:32, Frank Sundermeyer wrote:
Hi,

my name is Frank, I am the project manager for documentation in SUSE. The
whole doc team was on an offsite last week, so nobody from the team had a
chance to respond so far.

This has become a long thread, so I hope you bear with me when I answer/
comment in a single mail rather than replying to several posts
individually... .
Thanks Frank for taking the time to reply, and apologies that this all blew up
while you were at the offsite.

-----------------

On Tuesday, 12 March 2019 11:44:39 CET Ancor Gonzalez Sosa wrote:

I usually read complaints about the bad state of openSUSE documentation.
Ancor, this is a rather vague and general statement, can you please provide
more details? Questions that immediately come to my mind are:

* Does this refer to the openSUSE manuals at http://doc.opensuse.org/ or to
the openSUSE Wiki at http://en.opensuse.org/? Both?
* Where have you read these complaints and have they been passed on to the
Doc team or the Wiki team? If so, what happened to the feedback?

Maybe we can use Season of Docs (the Google's equivalent to Summer of
Code) to fix some stuff.
Maybe we should first find out what needs fixing, where is this needed and
how to integrate existing resources... .

I agree. Google's initiative is certainly interesting (and it's always nice to
see people caring about open source docs), but it's also set up for groups and
writers who have a plan in place, and processes to enable writers to
contribute. At this point, we don't really have that. That said, assuming
Google offer the program again next year, it could be feasible, if we have
managed to get a community effort off the ground by then.

----------------
On Thursday, 14 March 2019 00:35:19 CET Lana Brindley wrote:

that even the docs mailing list got shut down a little while ago
We decided to shut it down because there was no traffic at all on this list
for one year... . If needed/wanted, we can set it up again on short notice.
Just let me know...
Yes, please!

On Thursday, 14 March 2019 03:35:25 CET Lana Brindley wrote:

Since there's no mailing list or IRC any more
That is not true - #opensuse-doc on Freenode exists since many years and the
SUSE doc team is present.
Right now I see five people in that channel (including myself), and I've been
sitting in there for close to nine months now, with no interaction. Seems like
the definition of a dead channel to me. Slack has the extra added benefit of
providing scrollback and threading, so it tends to work better for people in
different timezones, because the conversation doesn't need to be synchronous
like IRC. I also think there's value in being on the same platform as the Write
the Docs community.

On Saturday, 16 March 2019 04:32:41 CET Lana Brindley wrote:

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.
I know from personal experience that many discussions in the community
(regardless of the topic) end in tools discussions. Before we open that can
of worms, I suggest to concentrate on content, collaboration and processes
first ;-D.

I agree, and having been through community-based conversation projects in the
past, it's important to get the team structure and processes right first. It's
an important consideration, though, and I don't want it to be forgotten in all
the political discussion.

----------------
On Thursday, 14 March 2019 09:02:22 CET Sarah Julia Kriesch wrote:

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.
This is no longer true since more than 3½ years (June 2015). Since then,
_all_ SUSE product documentation is publically hosted on GitHub and licensed
under an openSource license (GFDL, Apache 2.0, Creative Commons). The SUSE
doc team happily accepts pull requests, bug reports and other help.
The openSUSE documentation that is hosted on http://doc.opensuse.org/, for
example, is hosted at https://github.com/SUSE/doc-sle (SLES, SLED, and
openSUSE documenation are generated from the same source).
I suspect from this conversation thread that the invitation to make PRs to the
doc team hasn't been well publicised. Another issue I see is that while the
documentation is living in github, it's not being treated as docs-as-code, but
rather long-form documentation, which makes it much harder to make quick
patches.

Again, we are open for cooperation and collaboration. We have NO intention
at all to exclude the community.

BTW: The complete doc toolchain the doc team is using is also hosted on
GitHub and is used by people from outside SUSE.
The _complete_ work the SUSE doc team does is public and transparent for
everyone.

This is great, and it gives us a really good starting point for a community
effort.

On Thursday, 14 March 2019 10:33:46 CET Sarah Julia Kriesch wrote:

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.
[...]
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.
I was involved in these conversations and supported the solution you
mentioned above. In hindsight, it would have been better to not make this
promise. Not because we did not want to help. Quite the opposite. We made
this promise because we really _wanted_ to help. Back then the doc team was
under heavy work load (and it still is). We had hoped to find time to
squeeze in the work for the wiki (because we wanted to). It turned out that
it did not work out. And still does not.
I should have let you know about this much earlier. I failed to do so and
you have every right to be angry about us not fulfilling our part of the
agreement.
But be rest assured that it was not done because of disrespect for the
community, but because of lack of resources.
----------------
On Thursday, 14 March 2019 10:06:57 CET Simon Lees wrote:

But still it is technically possible to create a pull
request.
Yes! And bug reports, if you prefer that.

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.
Reviewing pull requests is part of our daily work and should be doable
(unless you do not attempt to rewrite everything with several hundered
requests ;-D). We may not always react within hours, but no work will be
lost or ignored.
the same is true for bug reports - they will usually take longer to get
fixed, but we will not ignore them.

Maybe it
makes sense to do the work in some other "New openSUSE feature branch",
Our tool chain and DocBook XML make it possible to create parts of the
documentation that is only valid for one product flavor (openSUSE in this
case). This is true for single words, sections, chapters or even whole
guides. Therefore adding openSUSE-specific content should not be a problem.
That's quite an unwieldy feature in Docbook, but it's a good beginning.
at worst its possible to fork the documentation into openSUSE's github
I hope it will not come to this - all parties would lose in this case.
I agree, and as I said in an earlier mail it only makes sense if the internal
docs team is hostile to patches, which it would seem you are not.

There might be other ways as well, but the best people to work that
through with is SUSE's documentation team.
That would really be appreciated. And I am volunteering to continue this
discussion with you - just let me know where (in case it is moved somewhere
else).

I think the suggestion was to move to opensuse-web, so I have added them to
this mail.

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 >