[opensuse-web] Re: [opensuse-project] Google's Season of Docs
Gesendet: Donnerstag, 14. März 2019 um 11:53 Uhr Von: "Simon Lees" <sflees@suse.de> An: opensuse-project@opensuse.org Betreff: Re: [opensuse-project] Google's Season of Docs
On 14/03/2019 20:03, Sarah Julia Kriesch wrote:
Gesendet: Donnerstag, 14. März 2019 um 10:06 Uhr Von: "Simon Lees" <sflees@suse.de> An: opensuse-project@opensuse.org 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@suse.de> An: opensuse-project@opensuse.org 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.
Cheers
--
Simon Lees (Simotek) http://simotek.net
Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 Then let's discuss this topic on the opensuse-web mailing list. That's the mailing list with our wiki Contributors and interested Community Members for the openSUSE Documentation at the moment.
Best regards, Sarah -- To unsubscribe, e-mail: opensuse-web+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-web+owner@opensuse.org
Hello lovely opensuse-web people! There has been a thread over on the opensuse-project list about community-based documentation (starts here: https://lists.opensuse.org/opensuse-project/2019-03/msg00033.html), and Sarah pointed out that refugees from the now closed docs list are hanging out here, so hi! o/ By way of introduction, I'm a SUSE technical writer but I'm not working with the internal docs team, I'm embedded in an engineering team instead. Over the years, I have been involved with other open source documentation projects, and it's breaking my heart that openSUSE doesn't seem to have an active community. I understand that there's some water under this bridge, so my next step is to go and have a chat to the internal docs team to work out how a community docs team can work with them in a sustainable way. I know they are under a lot of pressure, so it's important that any future plans don't put any extra stress on their resources. In the meantime, I'd love to see a show of hands of who is interested in contributing to a community docs effort, and find out what range of skills we have available. Feel free to reply to this mail and let me know how you would like to contribute. I'll gather a list of interested parties and make sure I keep you all informed. Finally, would people be generally in favour of a Slack channel (or some alternative) where we can discuss the project? Lana On 14/3/19 9:09 pm, Sarah Julia Kriesch wrote:
Gesendet: Donnerstag, 14. März 2019 um 11:53 Uhr Von: "Simon Lees" <sflees@suse.de> An: opensuse-project@opensuse.org Betreff: Re: [opensuse-project] Google's Season of Docs
On 14/03/2019 20:03, Sarah Julia Kriesch wrote:
Gesendet: Donnerstag, 14. März 2019 um 10:06 Uhr Von: "Simon Lees" <sflees@suse.de> An: opensuse-project@opensuse.org 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@suse.de> An: opensuse-project@opensuse.org 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.
Cheers
--
Simon Lees (Simotek) http://simotek.net
Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 Then let's discuss this topic on the opensuse-web mailing list. That's the mailing list with our wiki Contributors and interested Community Members for the openSUSE Documentation at the moment.
Best regards, Sarah
-- 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-web+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-web+owner@opensuse.org
Hello Lana, Am 16.03.19 um 04:54 schrieb Lana Brindley:
In the meantime, I'd love to see a show of hands of who is interested in contributing to a community docs effort, and find out what range of skills we have available. Feel free to reply to this mail and let me know how you would like to contribute.
I am interested in contributing to a community docs effort but I don't know how I could contibute. So far I have edited and contributed some articles to the openSUSE-Wiki and I am familiar with Doc Book XML.
Finally, would people be generally in favour of a Slack channel (or some alternative) where we can discuss the project?
Slack would be ok for me, but I would prefer free alternatives. :-) Kind regards, Christian Imhorst -- To unsubscribe, e-mail: opensuse-web+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-web+owner@opensuse.org
On 3/16/19 7:38 PM, Christian Imhorst wrote:
Hello Lana,
Am 16.03.19 um 04:54 schrieb Lana Brindley:
In the meantime, I'd love to see a show of hands of who is interested in contributing to a community docs effort, and find out what range of skills we have available. Feel free to reply to this mail and let me know how you would like to contribute.
I am interested in contributing to a community docs effort but I don't know how I could contibute. So far I have edited and contributed some articles to the openSUSE-Wiki and I am familiar with Doc Book XML.
Finally, would people be generally in favour of a Slack channel (or some alternative) where we can discuss the project?
Slack would be ok for me, but I would prefer free alternatives. :-)
Currently we are experimenting in some openSUSE teams with a bridged Matrix / Discord / IRC setup so that could be an option it seems to make most people happy. There is already a #docs channel on openSUSE's Discord group adding the others wouldn't be hard. I'd also be happy to help, probably less from a writing documentation side and more on the everything else that needs to go with it. -- Simon Lees (Simotek) http://simotek.net Emergency Update Team keybase.io/simotek SUSE Linux Adelaide Australia, UTC+10:30 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B -- To unsubscribe, e-mail: opensuse-web+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-web+owner@opensuse.org
participants (4)
-
Christian Imhorst -
Lana Brindley -
Sarah Julia Kriesch -
Simon Lees