[opensuse-project] Google's Season of Docs
I usually read complaints about the bad state of openSUSE documentation. Maybe we can use Season of Docs (the Google's equivalent to Summer of Code) to fix some stuff. https://developers.google.com/season-of-docs/ I know we got no volunteers to organize participation of openSUSE in the latest Google Summer of Code and I'm NOT volunteering to do that work for GSoD. I'm just trying to be the spark that lights somebody else enthusiasm. ;-) Cheers. -- Ancor González Sosa YaST Team at SUSE Linux GmbH -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
OK, I'll be that guy ;) I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done? Lana On 12/03/2019 20:44, Ancor Gonzalez Sosa wrote:
I usually read complaints about the bad state of openSUSE documentation. Maybe we can use Season of Docs (the Google's equivalent to Summer of Code) to fix some stuff.
https://developers.google.com/season-of-docs/
I know we got no volunteers to organize participation of openSUSE in the latest Google Summer of Code and I'm NOT volunteering to do that work for GSoD. I'm just trying to be the spark that lights somebody else enthusiasm. ;-)
Cheers.
-- 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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
Hi On 14/03/2019 10:05, Lana Brindley wrote:
OK, I'll be that guy ;)
I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done?
Lana
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, 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.
On 12/03/2019 20:44, Ancor Gonzalez Sosa wrote:
I usually read complaints about the bad state of openSUSE documentation. Maybe we can use Season of Docs (the Google's equivalent to Summer of Code) to fix some stuff.
https://developers.google.com/season-of-docs/
I know we got no volunteers to organize participation of openSUSE in the latest Google Summer of Code and I'm NOT volunteering to do that work for GSoD. I'm just trying to be the spark that lights somebody else enthusiasm. ;-)
Cheers.
-- 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-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 14/03/2019 10:39, Simon Lees wrote:
Hi
On 14/03/2019 10:05, Lana Brindley wrote:
OK, I'll be that guy ;)
I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done?
Lana
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? 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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 3/13/2019 9:35 PM, Lana Brindley wrote:
On 14/03/2019 10:39, Simon Lees wrote:
Hi
On 14/03/2019 10:05, Lana Brindley wrote:
OK, I'll be that guy ;)
I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done?
Lana
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?
Lana
Lana (and others), I don't have a ton of spare time, but I'd be willing to be on a docs team. A perfect way for this Member Emeritus to get back in the game. 8-) I also have a lot of tech writers in my Twitter feed, and can spread the word that way. Cheers, Mike McCallister, who wrote "openSUSE Linux Unleashed" in a past life -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 14/03/2019 12:54, Mike McCallister wrote:
On 3/13/2019 9:35 PM, Lana Brindley wrote:
On 14/03/2019 10:39, Simon Lees wrote:
Hi
On 14/03/2019 10:05, Lana Brindley wrote:
OK, I'll be that guy ;)
I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done?
Lana
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?
Lana
Lana (and others),
I don't have a ton of spare time, but I'd be willing to be on a docs team. A perfect way for this Member Emeritus to get back in the game. 8-) I also have a lot of tech writers in my Twitter feed, and can spread the word that way.
Hooray! I also know a lot of Twittering tech writers, so once we have a good place to gather them, I'll put a call out. I know it's not open, but what about Slack or something? That's where the Write the Docs people are. 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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
Hello, On Thu, 14 Mar 2019 at 08:55, Lana Brindley <lbrindley@suse.de> wrote:
On 14/03/2019 12:54, Mike McCallister wrote:
On 3/13/2019 9:35 PM, Lana Brindley wrote:
On 14/03/2019 10:39, Simon Lees wrote:
Hi
On 14/03/2019 10:05, Lana Brindley wrote:
OK, I'll be that guy ;)
I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done?
Lana
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?
Lana
Lana (and others),
I don't have a ton of spare time, but I'd be willing to be on a docs team. A perfect way for this Member Emeritus to get back in the game. 8-) I also have a lot of tech writers in my Twitter feed, and can spread the word that way.
Hooray! I also know a lot of Twittering tech writers, so once we have a good place to gather them, I'll put a call out. I know it's not open, but what about Slack
Just to give some pointers, https://opensuse-asia.slack.com is active & widely used by openSUSE contributors from Asia. :-) Regards, Amey.
or something? That's where the Write the Docs people are.
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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
-- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 14/03/2019 14:54, Amey Abhyankar wrote:
Hello,
On Thu, 14 Mar 2019 at 08:55, Lana Brindley <lbrindley@suse.de> wrote:
On 14/03/2019 12:54, Mike McCallister wrote:
On 3/13/2019 9:35 PM, Lana Brindley wrote:
On 14/03/2019 10:39, Simon Lees wrote:
Hi
On 14/03/2019 10:05, Lana Brindley wrote:
OK, I'll be that guy ;)
I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done?
Lana
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?
Lana Lana (and others),
I don't have a ton of spare time, but I'd be willing to be on a docs team. A perfect way for this Member Emeritus to get back in the game. 8-) I also have a lot of tech writers in my Twitter feed, and can spread the word that way.
Hooray! I also know a lot of Twittering tech writers, so once we have a good place to gather them, I'll put a call out. I know it's not open, but what about Slack Just to give some pointers,
https://opensuse-asia.slack.com is active & widely used by openSUSE contributors from Asia. :-)
Thanks! Looks like you need an opensuse.org email address to join, though (not sure if Australia counts as "Asia" in this instance, either!) :( Although it seems as though the community isn't opposed to Slack, so perhaps that's a reasonable option for us. Lana
Regards, Amey.
or something? That's where the Write the Docs people are.
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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
-- 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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 14/03/2019 15:28, Lana Brindley wrote:
On 14/03/2019 14:54, Amey Abhyankar wrote:
Hello,
On Thu, 14 Mar 2019 at 08:55, Lana Brindley <lbrindley@suse.de> wrote:
On 14/03/2019 12:54, Mike McCallister wrote:
On 3/13/2019 9:35 PM, Lana Brindley wrote:
On 14/03/2019 10:39, Simon Lees wrote:
Hi
On 14/03/2019 10:05, Lana Brindley wrote: > OK, I'll be that guy ;) > > I can see that the OpenSUSE docs need some love and care (and that even the docs mailing list got shut down a little while ago :\ ). I've had some experience with open source docs communities in the past. What needs to be done? > > Lana > 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?
Lana Lana (and others),
I don't have a ton of spare time, but I'd be willing to be on a docs team. A perfect way for this Member Emeritus to get back in the game. 8-) I also have a lot of tech writers in my Twitter feed, and can spread the word that way.
Hooray! I also know a lot of Twittering tech writers, so once we have a good place to gather them, I'll put a call out. I know it's not open, but what about Slack Just to give some pointers,
https://opensuse-asia.slack.com is active & widely used by openSUSE contributors from Asia. :-)
Thanks! Looks like you need an opensuse.org email address to join, though (not sure if Australia counts as "Asia" in this instance, either!) :(
Although it seems as though the community isn't opposed to Slack, so perhaps that's a reasonable option for us.
Lana
Ahh, the places where you bump into another random Aussie, Australia counts as asia for now, openSUSE Asia summit is in Bali this year and the distance between you and Bali is potentially less then the distance between you and me so you should certainly try and come along. Anyway i'm also a member of that slack although I rarely join because I don't need another browser just to run another chat. Most openSUSE development discussion is still generally done on irc although there is a reasonable size community on discord now and the artwork team prefers that over irc as its easier to share artwork then IRC so thats also an option some communities also use telegram a lot. But really you can use whatever you all feel like. -- 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-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
Hello, On 3/14/19 12:54 PM, Amey Abhyankar wrote:
https://opensuse-asia.slack.com is active & widely used by openSUSE contributors from Asia. :-)
I'm sorry to go off-topic but being in Asia myself I didn't know about Slack being used. I will check it ouy :) -- Maurizio Galli (MauG) Xfce Team https://en.opensuse.org/Portal:Xfce -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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?
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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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. The wiki mailing list has been merged with opensuse-web now. Therefore, you can find our wiki Contributors on opensuse-web. It would be great to find a solution for a better cooperation for the documentation part at openSUSE. Thank you that you want to volunteer in this position between SUSE and openSUSE! Best regards, Sarah -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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. Cheers -- 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-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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. Best regards, Sarah -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
Gesendet: Donnerstag, 14. März 2019 um 10:33 Uhr Von: "Sarah Julia Kriesch" <ada.lovelace@gmx.de> An: "Simon Lees" <sflees@suse.de> Cc: opensuse-project@opensuse.org Betreff: Re: [opensuse-project] Google's Season of Docs
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.
Best regards, Sarah -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
P.S. Here is the meeting protocol by the Heroes Meeting (the guy by the Documentation Team had visited us for wiki update discussions): https://en.opensuse.org/openSUSE:Heroes/Meetings/20161202_Summary#mediawiki -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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 GPG Fingerprint: 5B87 DB9D 88DC F606 E489 CEC5 0922 C246 02F0 014B -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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@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.
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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 14/3/19 7:06 pm, Simon Lees wrote:
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.
Forking the repo only makes sense if the internal docs team is hostile to community contributions, and I'm optimistic that that isn't the case. I suspect it's more that the internal team is overwhelmed with internal work, and hasn't been able to keep up with community contributions. So, we need to come up with a way to manage community documentation that doesn't add extra burden on them. I will contact them through internal communication channels and come up with a few different options to take this forward. 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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 16/03/2019 13:59, Lana Brindley wrote:
On 14/3/19 7:06 pm, Simon Lees wrote:
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.
Forking the repo only makes sense if the internal docs team is hostile to community contributions, and I'm optimistic that that isn't the case. I suspect it's more that the internal team is overwhelmed with internal work, and hasn't been able to keep up with community contributions. So, we need to come up with a way to manage community documentation that doesn't add extra burden on them. I will contact them through internal communication channels and come up with a few different options to take this forward.
Thanks this is really the best way forward, I just thought i'd list all the options. -- 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
Hey, On 14.03.19 09:02, Sarah Julia Kriesch wrote:
documentation is only editable by the SUSE documentation team.
https://github.com/SUSE/doc-sle looks forkable to me... Henne -- Henne Vogelsang http://www.opensuse.org Everybody has a plan, until they get hit. - Mike Tyson -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 14/3/19 6:02 pm, 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?
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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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.
I'm so happy there are people out there!
The community is only allowed to edit the wiki and that is the documentation by the community at the moment.
That is actually quite disturbing to me. I'm going to follow up with the internal docs team to find out what's happening here from their perspective.
The wiki mailing list has been merged with opensuse-web now. Therefore, you can find our wiki Contributors on opensuse-web. Excellent, I'll sign up over there :) It would be great to find a solution for a better cooperation for the documentation part at openSUSE. Agreed. Without a community, open source is in name only. And as the WtD community like to say: "Docs or it didn't happen" ;)
Thank you that you want to volunteer in this position between SUSE and openSUSE!
I have some experience to bring from other open source docs projects, and I hate to see a good project linger without love. So, you are most welcome! L -- 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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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... . ----------------- 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... . ---------------- 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... 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. 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. ---------------- 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). 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. 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.
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.
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). -- Regards Frank Frank Sundermeyer, Project Manager Documentation SUSE Linux GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE Linux GmbH, GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) "Reality is always controlled by the people who are most insane" Dogbert -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
On 3/18/19 3:32 PM, Frank Sundermeyer wrote:
Hi,
[...]
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... .
Replying below to "my" part. ;-)
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?
The openSUSE wiki
* 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?
Usually in mailing lists. I have not passed that information because I believe that the not-so-shiny state of the Wiki is a more than known issue. I'm subscribed to the (now extinct) wiki ML and to the Spanish translators one, and my feeling is that everyone there assumes the situation is far from optimal. No need to repeat that over and over. :-)
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... .
Sure. And that's exactly what we need volunteers for. Applying for GSoD will imply quite some previous work. Cheers. -- Ancor González Sosa YaST Team at SUSE Linux GmbH -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
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@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org
participants (9)
-
Amey Abhyankar -
Ancor Gonzalez Sosa -
Frank Sundermeyer -
Henne Vogelsang -
Lana Brindley -
Maurizio Galli (MauG) -
Mike McCallister -
Sarah Julia Kriesch -
Simon Lees