Re: [opensuse-doc] Would like to contribute
Hello, Sorry for jumping on a running train. I participate in the Telegram group Attila mentioned in his first message below. I too think it would be awesome to get future and current openSUSE's users the best doc available. However before anything else perhaps we should clarify something. As I understand it, Attila's main point in his original message was to lower the entry-barrier for new openSUSE users, not to necessarily have the wiki removed and the doc rewritten. If this is correct, then I think I share his goal, as I think the easily accessible yet outdated wiki might intercept or delay users who actually need to get the docs, while not necessarily creating a very enticing experience. Of course every open source project needs active volunteers, and a wiki makes this clear, But I think that the best way to motivate new users is to first offer them information that is relevant to their issues (and we know what issues new users are most likely to run into), and to present it in an enjoyable way. Which leads me to believe that: 1) a first layer of information catering to new users, anticipating their needs and guiding them to better understand their issues, is very valuable 2) the previous condition cannot be met only with static doc (i.e. a manual or handbook in the sense of docs.opensuse.org), because a manual is not enticing to everybody and does not unwrap information in layers relevantly connected to common issues (being linear and not interactive) 3) the current doc is awesome and I think it can stay the way it is because it still performs an important role (i.e. a basic "source of truth" for users who most need it) Do we all agree on this? If so, and if I am understanding Attila's initiative correctly, we'll need more than punctual, spontaneous amendments to the docs. We need to discuss and coordinate to get contents presented in a more perspicuous way. We need a "contents redesign".. What do you think? Best, Adrien ------------------------------------ Hi Lana, Thank you for your help, much appreciated. The repo you linked to seem to create content for doc.opensuse.org instead of the openSUSE wiki (https://en.opensuse.org/Main_Page) or the wiki is being phased out and things are being moved over to doc.opensuse.org? To be honest I much prefer the format of doc.opensuse.org. Removing the wiki might be a good idea or forwarding it to the docs. Definitely missing content, the opening page would require some tuning and an easier way to find it maybe? Hopefully can assist with the work in the very near future after got the technicalities out of the way. Chances are that I'm going to take you up on your offer and disturb you with my questions ;) Attila ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, September 9, 2020 7:40 AM, Lana Brindley <lbrindley@xxxxxxx> wrote: Hi Attila, This is a common refrain! It is possible to contribute directly to the openSUSE documentation, the repo is here: https://github.com/SUSE/doc-sle Personally, I think it is more valuable to contribute to the docs directly, rather than having great content tucked away on an unused wiki, but I also appreciate that contributing directly to a repo like this can be a little daunting if you are not a trained technical writer. With that in mind, I'm absolutely happy to help you out if you have questions :) Lana On 08/09/2020 23:51, adathor wrote: Hi openSUSE-Doc Team, My name is Attila (adathor). We had a fairly long and interesting conversation yesterday on the official Telegram group in regards to the openSUSE wiki and the potential problems around it due to the lack of contributors. Me and probably a few of us from that group would be able to put in some time and help improving the wiki. Checked the Wiki Team page, but considering that it hasn't been updated since 2018 thought it's best to reach out and educate myself about the current status of the Wiki and where is it that you guys would require the most help. Was also thinking a little about how we could help changing up the opening page of the Wiki with guides for - installing openSUSE [$distro] to help first time users - this could also include a YouTube video -, - adding information on tools like Snapper, Opi, transactional-updates, rebootmgr, helth-checker etc. - Distribution overview, that would include the differences compared to other distros and the benefits of using oS, - Clear contribution options and guide, - FAQ - Links to international communities. Any guidance on how to contribute, what are your priorities and the current status of the Wiki would be much appreciated. A. -- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things." -------------------------------------------------------------------------------------------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx To contact the owner, e-mail: opensuse-doc+owner@xxxxxxxxxxxx -- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-doc+owner@opensuse.org
Hi Adrien, Yes, I think you're right that openSUSE docs needs a strategy, and that the current system is less than ideal. I have a whole lot of ideas about that (and experience doing it in other communities), but we really need a team of people to make it happen. Absolutely happy to be part of that team, if the enthusiasm is there! Ideally, that team would include someone from the central SUSE docs team (who own the repo)*, because it could involve a significant departure from the way they currently use the repo to generate the SLE docs. As to the wiki, it predates my involvement in openSUSE, although my understanding is that it was created as a way to lower the barrier to entry for outside contributions. However it also means that those contributions get stuck in the wiki and never make it into the official docs, which is a problem. Either way, I am glad that there is conversation happening on this. I have tried a couple of times to get the issue raised, to no avail. It's the main reason I restarted this mailing list, but it sounds like I need to join the Telegram group, too ;) Lana * Just to be clear, I'm not part of that team in any official capacity. On 10/09/2020 08:24, Adrien Glauser wrote:
Hello,
Sorry for jumping on a running train. I participate in the Telegram group Attila mentioned in his first message below. I too think it would be awesome to get future and current openSUSE's users the best doc available. However before anything else perhaps we should clarify something. As I understand it, Attila's main point in his original message was to lower the entry-barrier for new openSUSE users, not to necessarily have the wiki removed and the doc rewritten.
If this is correct, then I think I share his goal, as I think the easily accessible yet outdated wiki might intercept or delay users who actually need to get the docs, while not necessarily creating a very enticing experience. Of course every open source project needs active volunteers, and a wiki makes this clear, But I think that the best way to motivate new users is to first offer them information that is relevant to their issues (and we know what issues new users are most likely to run into), and to present it in an enjoyable way. Which leads me to believe that:
1) a first layer of information catering to new users, anticipating their needs and guiding them to better understand their issues, is very valuable 2) the previous condition cannot be met only with static doc (i.e. a manual or handbook in the sense of docs.opensuse.org), because a manual is not enticing to everybody and does not unwrap information in layers relevantly connected to common issues (being linear and not interactive) 3) the current doc is awesome and I think it can stay the way it is because it still performs an important role (i.e. a basic "source of truth" for users who most need it)
Do we all agree on this? If so, and if I am understanding Attila's initiative correctly, we'll need more than punctual, spontaneous amendments to the docs. We need to discuss and coordinate to get contents presented in a more perspicuous way. We need a "contents redesign"..
What do you think?
Best,
Adrien ------------------------------------ Hi Lana,
Thank you for your help, much appreciated.
The repo you linked to seem to create content for doc.opensuse.org instead of the openSUSE wiki (https://en.opensuse.org/Main_Page) or the wiki is being phased out and things are being moved over to doc.opensuse.org? To be honest I much prefer the format of doc.opensuse.org. Removing the wiki might be a good idea or forwarding it to the docs. Definitely missing content, the opening page would require some tuning and an easier way to find it maybe? Hopefully can assist with the work in the very near future after got the technicalities out of the way.
Chances are that I'm going to take you up on your offer and disturb you with my questions ;)
Attila
‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, September 9, 2020 7:40 AM, Lana Brindley <lbrindley@xxxxxxx> wrote:
Hi Attila,
This is a common refrain! It is possible to contribute directly to the openSUSE documentation, the repo is here: https://github.com/SUSE/doc-sle
Personally, I think it is more valuable to contribute to the docs directly, rather than having great content tucked away on an unused wiki, but I also appreciate that contributing directly to a repo like this can be a little daunting if you are not a trained technical writer. With that in mind, I'm absolutely happy to help you out if you have questions :)
Lana
On 08/09/2020 23:51, adathor wrote:
Hi openSUSE-Doc Team, My name is Attila (adathor). We had a fairly long and interesting conversation yesterday on the official Telegram group in regards to the openSUSE wiki and the potential problems around it due to the lack of contributors. Me and probably a few of us from that group would be able to put in some time and help improving the wiki. Checked the Wiki Team page, but considering that it hasn't been updated since 2018 thought it's best to reach out and educate myself about the current status of the Wiki and where is it that you guys would require the most help. Was also thinking a little about how we could help changing up the opening page of the Wiki with guides for
- installing openSUSE [$distro] to help first time users - this could also include a YouTube video -, - adding information on tools like Snapper, Opi, transactional-updates, rebootmgr, helth-checker etc. - Distribution overview, that would include the differences compared to other distros and the benefits of using oS, - Clear contribution options and guide, - FAQ - Links to international communities.
Any guidance on how to contribute, what are your priorities and the current status of the Wiki would be much appreciated. A.
--
Lana Brindley @Loquacities Technical Writer - SUSE Manager
"The question is," said Alice, "whether you can make words mean so many different things."
--------------------------------------------------------------------------------------------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-doc+unsubscribe@xxxxxxxxxxxx To contact the owner, e-mail: opensuse-doc+owner@xxxxxxxxxxxx
-- Lana Brindley @Loquacities Technical Writer - SUSE Manager "The question is," said Alice, "whether you can make words mean so many different things." -- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse-doc+owner@opensuse.org
participants (2)
-
Adrien Glauser -
Lana Brindley