Project Description

Update: The invitation to contribute to open source and SUSE documentation does NOT expire. If you want to collaborate with us, contact us at doc-team@suse.com.

During Hack Week 21, we would like to invite EVERYONE interested in contributing to SUSE documentation and/or in understanding how the docs are created, to interact with us – and feel more comfortable.

To that purpose, on Wednesday and Thursday, we will be offering a “universal workshop” consisting of several overview and hands-on sessions.

Goal for this Hackweek

Our session topics range from overview-like information, such as getting to know the doc team, including our tasks and responsibilities and workflow, or what kinds of documents we offer, to easy-to-do tasks, such as editing a document via PDF or a browser or submitting an issue, up to working extensively with the documentation toolchain. The different sessions address participants and volunteers with different levels of background and (language or technical) knowledge. The slots are marked respectively as “overview” (might be of broader interest), “newbie” (platform agnostic, for non-Linux users and/or non-techies), or “advanced” (for techies and developers).

The goal is to continuously and collaboratively enhance the SUSE documentation for the benefit of our entire ecosystem.

Resources

UPDATE: Please find all session recordings in the SUSE Documentation Team space in SharePoint.

PLEASE DON’T THINK THIS IS NOTHING FOR YOU IF YOU ARE A WINDOWS DESKTOP USER or if you don’t have a technical background. EVERYONE can contribute to documentation, no matter what your expertise level is. As a newbie or non-techie, for example, you could just READ a document and tell us if it is understandable, or if instructions are explained way too complicated. You can do a language review and checking docs for typing errors. As a techie or developer, you could do a sanity check for instructions, or add missing information. There are many options for contributions for any level of background or expertise.

Our processes and toolchain are open and make contributions from external parties easy. We highly welcome and appreciate every external participant.

Attention: If you are interested in attending one or more sessions, please click “Join this project” and – very important – let us now in the comment area below by typing the session number which session(s) you would like to join (or, if you prefer, drop me a private mail at meike.chabowski@suse.com). See session dates, times, and participation links below. Some sessions (targeting different levels) are scheduled in parallel. Some sessions might be subject to change, and if we don’t have people signing up for specific sessions, we might still drop the respective slot.

Session 1: SUSE Documentation team and responsibilities (OVERVIEW)

Everyone knows that SUSE “is doing documentation”. But do you know what exactly is part of the tasks of the doc team? Or do you know how the tasks are split among the team? Or whom to approach for specific products or questions? This session is the right start for you if you want to understand a bit better what the documentation team is really doing – and who is doing what.

Who: Everyone, newbie and advanced, Windows/Linux/Mac users

Where: Teams appointment/link session 1

When: Wednesday June 29th, 9:15 am - 9:45 am CEST

Session 2: Current SUSE docs workflow/toolchain/processes (OVERVIEW) (Jana Jaeger)

You might have heard that “the documentation team writes in DocBook” or “uses DAPS”, and “maintains DocServ”. But – what does that mean? What are these tools good for? How do they interact? What is the “flow”? This session provides a high level overview of the tools that are used to create the SUSE documentation, and some background why we use them. We are NOT going into technical details. The purpose of this session is very simple: understand how the docs are created, to understand to what degree you might be able to contribute.

Who: Everyone, newbie and advanced, Windows/Linux/Mac users

Where: Teams appointment/link session 2

When: Wednesday June 29th, 10:00 am - 10:30 am CEST

Session 3: Which types of documents are created by SUSE documentation (OVERVIEW) (Meike Chabowski)

We often talk about “product documentation”, “SBP”, “TRD”, “Smart Docs” – but do you really know what that means? Or which kind of document might target which users? And why we are not just simply offer “guides” and “manuals”? This information might help make you understand where you could chime in and contribute.

Who: Everyone, newbie and advanced, Windows/Linux/Mac users

Where: Teams appointment/link session 3

When: Wednesday June 29th, 10:45 am - 11:15 am CEST

Session 4: Technical writing for non-writers: Hands-on session with examples and writing exercises (INTRO and HANDS-ON) (Tanja Roth)

You need to write (technical) texts now and then? But you are not sure how to structure them, how to phrase your content, or how to best address your readers? This hands-on session shows you how to optimize texts to make them easier to understand (and translate). Get to know universal principles that can be applied to a wide variety of text types - including release notes, bug reports, error messages, or e-mails.

Who: Newbies and advanced. Windows/Linux/Mac users. Everyone who is interested in writing technical information

Where: Teams appointment/link session 4

When: Thursday June 30th, 10:00 am - 12:00 pm CEST

Session 5: Localization (and terminology) at SUSE (OVERVIEW) (Julia Faltenbacher, Padraig Dillon)

Learn how the SUSE localization team works and which services they offer. Experience the daily routine, processes and tools of a translator. Hear what you can do to help the localization team, lower the translation costs and simply make the life of our translators easier. We will also introduce you into the world of terminology: see how terminology work is done and why it is important - and get surprised on which great project the localization team is currently working on.

Who: Newbies and advanced. Windows/Linux/Mac users. Everyone who is interested in writing technical information

Where: Teams appointment/link session 5

When: Wednesday June 29th, 11:30 am - 12:30 pm CEST

Session 6: The documentation writing style (OVERVIEW) (Daria Vladykina)

Learn more about the documentation style guide, why it has been created, what it covers, where to find it, and how to use it. Hear also about additional tools like the spell checker, the style checker and the link checker, which make writing and editing documents a bit easier. Get some examples, and probably try / check it out yourself?

Who: Advanced. Linux users. Everyone who wants to write tech docs and dares to use the doc toolchain

Where: Teams appointment/link session 6

When: Wednesday June 29th, 2:00 pm - 2:45 pm CEST

Session 7: Editing and writing in DocBook XML (HANDS-ON)

Our documentation format of choice is DocBook XML. We heard people saying that it is “too complicated” or “too complex”. But it has many advantages. And if you understand the way of tagging, it is no rocket science anymore. The purpose of this session is to enable you to edit documentation sources written in DocBook yourself, or to even write/contribute content.

Who: Advanced. Linux users. Everyone who wants to write tech docs and dares to use the doc toolchain

Where: Teams appointment/link session 7

When: Thursday June 30th, 2:15 pm - 4:00 pm CEST Attention this session might be subject to change (date and/or time)

Session 8: Easily edit documents in GitHub, NOT being a techie or even a Linux desktop user! (INTRO and HANDS-ON) (Meike Chabowski)

Our HTML documents provide several options to give feedback for a piece of documentation. You can for example click a link “Edit source”. You don’t have to be afraid to do so – even if you (think you) are not a technician, or if you are not a Linux desktop user. Our documents sources are hosted in GitHub. And GitHub is not only platform-agnostic, but also offers a browser user interface and lets you work online. No tool downloads or deeper technical knowledge are needed. The purpose of this session is to explain at a high level what GitHub is and why it is a great tool for cooperation, how you can easily edit documents online, how you can submit a so-called “GitHub issue” to request changes, additions, or just to give feedback for a document – everything supported with some examples and hands-on activities.

Who: Newbies. Windows/Linux/Mac users. Everyone who wants to help editing. No tech background needed.

Where: Teams appointment/link session 8

When: Wednesday June 29th, 4 pm - 4:45 pm CEST

Session 10: Requesting documentation via Jira (HANDS-ON) (Tanja Roth)

Jira is THE tool for planning and organizing products at SUSE. This also includes documentation tasks. The purpose of this session is to understand how to request documentation for your product or piece of software.

Who: Advanced. Linux users. Everyone who wants to enhance documentation.

Where: Teams appointment/link session 10

When: ATTENTION ATTENTION This session had to be moved to Thursday June 30th, 4:30 pm - 5:15 pm CEST (from Wednesday June 29th, 3 pm - 3:45 pm CEST)

Session 11: Setting up your own documentation toolchain (HANDS-ON) (Frank Sundermeyer)

If you followed the toolchain overview session, you’ve got an idea which tools we are using. And now you want to set up your own documentation environment, but you don’t know how? The purpose of this session is to show you which tools to use, where to get them from, and how to install them.

Who: Advanced. Linux users. Everyone who plans to work locally with an own documentation infrastructure.

Where: Teams appointment/link session 11

When: Thursday June 30th, 9:00 am - 9:45 am CEST

Session 12: A deep dive into GitHub for documentation (HANDS-ON) (Jana Halackova)

GitHub is an important tool in our toolchain. It hosts our documentation sources, and is the fundament of our “docs as code” approach. In this session, you will first get an overview of all documentation repositories (“what do I find where” / “what to look up if I want to contribute to product xyz”). The main focus however is on how to clone or fork a repo, how to do a Pull Request correctly (including adding reviewers etc.), or why we have validation and CI via GitHub actions. And much more. The purpose is to enable technical colleagues or developers not yet fully familiar with GitHub to work on the SUSE documentation or to create their own docs using the documentation toolchain.

Who: Advanced. Linux users. Everyone who plans to work locally with an own documentation infrastructure.

Where: Teams appointment/link session 12

When: Wednesday June 29th, 10:00 am - 12:00 pm CEST (parallel track)

Session 13: How to use DAPS (INTRO/TUTORIAL)

DAPS helps you author and publish documentation written in DocBook XML or AsciiDoc. DAPS handles everything from short articles by a single author to large documentation projects by many authors. It is a command-line tool and works on Linux. This session explains how to use DAPS.

Who: Advanced. Linux users. Everyone who plans to create own technical documents.

Where: Teams appointment/link session 13

When: Thursday June 30th, 1:00 pm - 2:00 pm CEST

Session 14: How the SUSE documentation is published – Docserv (OVERVIEW)

Docserv is a tool to publish and semi-automatically update large-scale documentation websites accommodating multiple products, product versions, and localizations. It focuses on allowing publication of DocBook/AsciiDoc content that is compatible with DAPS. However, it can also accommodate links to other sources of documents. We build the SUSE documentation via Docserv, and can publish it to different servers for different purposes. Specific configs define how and where to publish. If you are interested to understand how this final but crucial component of our toolchain works, let us know and we will sign you up.

Who: Advanced. Linux users.

Where: Teams appointment/link session 14

When: Thursday June 30th, 4:00 pm - 4:30 pm CEST Attention this session might be subject to change (date and/or time)

This project is part of:

Hack Week 21

Activity

  • over 2 years ago: nicoladm liked this project.
  • over 2 years ago: fsundermeyer joined this project.
  • over 2 years ago: jufa liked this project.
  • over 2 years ago: jjaeger liked this project.
  • over 2 years ago: daria.vladykina liked this project.
  • over 2 years ago: deneb_alpha joined this project.
  • over 2 years ago: chabowski liked this project.
  • over 2 years ago: dmathern joined this project.
  • over 2 years ago: dmathern left this project.
  • over 2 years ago: dmathern joined this project.
  • over 2 years ago: dmathern liked this project.
  • over 2 years ago: Monzicle liked this project.
  • over 2 years ago: ConradBachman joined this project.
  • over 2 years ago: rainerkoenig joined this project.
  • over 2 years ago: deneb_alpha liked this project.
  • over 2 years ago: Monzicle joined this project.
  • over 2 years ago: rebeccazhuo liked this project.
  • over 2 years ago: anthidote liked this project.
  • over 2 years ago: anthidote joined this project.
  • over 2 years ago: bchou liked this project.
  • over 2 years ago: jufa joined this project.
  • over 2 years ago: Nycticorax joined this project.
  • over 2 years ago: Nycticorax liked this project.
  • over 2 years ago: GraceWang joined this project.
  • over 2 years ago: ta-ro joined this project.
  • All Activity

    Comments

    • anthidote
      over 2 years ago by anthidote | Reply

      I'm interested in Session 7 and 14 on Thursday. :)

      Already have a working DAPS environment, so I'll save the time from 13-14 for lunch.

      Sorry, but editor habits are hard to lose. What happened to Session 9? ;)

    • chabowski
      over 2 years ago by chabowski | Reply

      Hi @anthidote - great thanks for your comments and for your interest in our project :-). Session 9 has hiddenly been cancelled, as there was no interest so far. But as we do not do "strict" sessions but hopefully more conversational talks, depending on how many people is joining the sessions you picked, we can probably also quickly show that part.

      • anthidote
        over 2 years ago by anthidote | Reply

        Ah, ok. I'll drop by on Thursday afternoon in any case.

        I've used asciidoc + DAPS to create a desktop guide for new joiners, but I'd like to check out DocBook XML. While asciidoc is nice for individual standalone documents, XML is necessary for the feature to build documentation sites. Perhaps that feature would helped to avoid the awful link rot that we have in Support's "para-documentation"... ;)

        • chabowski
          over 2 years ago by chabowski | Reply

          ****I personally love DocBook (and had to learn it from scratch, as I was coming from SUSE Product Marketing to Documentation). People says it is "complex", but I like it much better than AsciiDoc - DocBook talks "clear text", if you do something wrong, you can easily identify where and what, while with AsciiDoc, you can quickly mess up format by adding a mini small period somewhere without realizing it - and then you are lost because you don't find the error .... add-emoji ... And if I can learn DocBook, everybody else can, too add-emoji

          • anthidote
            over 2 years ago by anthidote | Reply

            I've definitely already run into those exact limitations of Asciidoc... ordered lists are picky

            • chabowski
              over 2 years ago by chabowski | Reply

              Yep - horrible ... And when you edit docs in AsciiDoc for others, it is so hard to fix certain things, as you need to find the "starting point" of the error. :-

    • gdsouza
      over 2 years ago by gdsouza | Reply

      Will the sessions be recorded and available later?

      • chabowski
        over 2 years ago by chabowski | Reply

        Hi, yes we try to record them more or less all. Some of them might not make sense to be recorded/posted, above all if they are too much "hands-on", but we will hit the "record" button anyway. But please don't expect the sessions to be "conference-like" presentations. We would love to make them more conversational, and if possible, interactive.

        • chabowski
          over 2 years ago by chabowski | Reply

          Glen, which sessions are you most interested in? I can add you to the Teams invitation, so you get the link / recording in any case.

    • rainerkoenig
      over 2 years ago by rainerkoenig | Reply

      Meike, count me in. Being a "newcomer" to SUSE (I started in August 2021), I'm still suffering from the impression, that so many of SUSE's knowledge is in the heads and not in the files. add-emoji

      For the convenience I created a Google Calendar with the schedule above.

      I have some experience in Docbook and DAPS already, used it a while ago to document the processes in my sports club where I'm the president for a log time now. I will see that I attend the short sessions on Wednesday and the ones on Thursday.

      • chabowski
        over 2 years ago by chabowski | Reply

        Hi Rainer - super, glad you would like to join us! With a year of SUSE experience, you are already an "alter Hase" ;-) ... I have scheduled the sessions in Teams. If there are specific sessions you are interested in, I will also forward the link/invitation. But thanks for the Google schedule!!

    • Monzicle
      over 2 years ago by Monzicle | Reply

      Hi, I am interested in session 1-5 and session 8. Complete newbie but I am curious add-emoji

      • chabowski
        over 2 years ago by chabowski | Reply

        Hi Monica, very cool! I am about to reply to you directly on your email add-emoji . I will sign you up for sessions 1-5 plus 8 - you will get some Teams invitations. Complete newbie is absolutely fine. We are not doing "conference-like" sessions, or a test or so. This project is really to give some insight, show where you can contribute if you want, even if you are not a techie, and to have some fun!

    • chabowski
      over 2 years ago by chabowski | Reply

      Hi Monica, very cool! I am about to reply to you directly on your email add-emoji . I will sign you up for sessions 1-5 plus 8 - you will get some Teams invitations. Complete newbie is absolutely fine. We are not doing "conference-like" sessions, or a test or so. This project is really to give some insight, show where you can contribute if you want, even if you are not a techie, and to have some fun!

    • ConradBachman
      over 2 years ago by ConradBachman | Reply

      Hi, I would like to join sessions 1,2,4,6,8,10 and 11. I would love to join for session 12 as well but that is running in parallel with session 4. I might have to jump out of some sessions as i am working on a project already with my team. :)

      • chabowski
        over 2 years ago by chabowski | Reply

        Hi Conrad - thank you for your interest - and done! You should have appointment invitations in your inbox/calendar.

    • chabowski
      over 2 years ago by chabowski | Reply

      Thank you all for your contributions and support of the project - we had a lot of fun!

      • Nycticorax
        over 2 years ago by Nycticorax | Reply

        Was a toll! Thanks for organizing this! add-emoji

    Similar Projects

    Uyuni developer-centric documentation by deneb_alpha

    Description

    While we currently have extensive documentation on user-oriented tasks such as adding minions, patching, fine-tuning, etc, there is a notable gap when it comes to centralizing and documenting core functionalities for developers.

    The number of functionalities and side tools we have in Uyuni can be overwhelming. It would be nice to have a centralized place with descriptive list of main/core functionalities.

    Goals

    Create, aggregate and review on the Uyuni wiki a set of resources, focused on developers, that include also some known common problems/troubleshooting.

    The documentation will be helpful not only for everyone who is trying to learn the functionalities with all their inner processes like newcomer developers or community enthusiasts, but also for anyone who need a refresh.

    Resources

    The resources are currently aggregated here: https://github.com/uyuni-project/uyuni/wiki


    ddflare: (Dynamic)DNS management via Cloudflare API in Kubernetes by fgiudici

    Description

    ddflare is a project started a couple of weeks ago to provide DDNS management using v4 Cloudflare APIs: Cloudflare offers management via APIs and access tokens, so it is possible to register a domain and implement a DynDNS client without any other external service but their API.

    Since ddflare allows to set any IP to any domain name, one could manage multiple A and ALIAS domain records. Wouldn't be cool to allow full DNS control from the project and integrate it with your Kubernetes cluster?

    Goals

    Main goals are:

    1. add containerized image for ddflare
    2. extend ddflare to be able to add and remove DNS records (and not just update existing ones)
    3. add documentation, covering also a sample pod deployment for Kubernetes
    4. write a ddflare Kubernetes operator to enable domain management via Kubernetes resources (using kubebuilder)

    Available tasks and improvements tracked on ddflare github.

    Resources

    • https://github.com/fgiudici/ddflare
    • https://developers.cloudflare.com/api/
    • https://book.kubebuilder.io


    Testing and adding GNU/Linux distributions on Uyuni by juliogonzalezgil

    Join the Gitter channel! https://gitter.im/uyuni-project/hackweek

    Uyuni is a configuration and infrastructure management tool that saves you time and headaches when you have to manage and update tens, hundreds or even thousands of machines. It also manages configuration, can run audits, build image containers, monitor and much more!

    Currently there are a few distributions that are completely untested on Uyuni or SUSE Manager (AFAIK) or just not tested since a long time, and could be interesting knowing how hard would be working with them and, if possible, fix whatever is broken.

    For newcomers, the easiest distributions are those based on DEB or RPM packages. Distributions with other package formats are doable, but will require adapting the Python and Java code to be able to sync and analyze such packages (and if salt does not support those packages, it will need changes as well). So if you want a distribution with other packages, make sure you are comfortable handling such changes.

    No developer experience? No worries! We had non-developers contributors in the past, and we are ready to help as long as you are willing to learn. If you don't want to code at all, you can also help us preparing the documentation after someone else has the initial code ready, or you could also help with testing :-)

    The idea is testing Salt and Salt-ssh clients, but NOT traditional clients, which are deprecated.

    To consider that a distribution has basic support, we should cover at least (points 3-6 are to be tested for both salt minions and salt ssh minions):

    1. Reposync (this will require using spacewalk-common-channels and adding channels to the .ini file)
    2. Onboarding (salt minion from UI, salt minion from bootstrap scritp, and salt-ssh minion) (this will probably require adding OS to the bootstrap repository creator)
    3. Package management (install, remove, update...)
    4. Patching
    5. Applying any basic salt state (including a formula)
    6. Salt remote commands
    7. Bonus point: Java part for product identification, and monitoring enablement
    8. Bonus point: sumaform enablement (https://github.com/uyuni-project/sumaform)
    9. Bonus point: Documentation (https://github.com/uyuni-project/uyuni-docs)
    10. Bonus point: testsuite enablement (https://github.com/uyuni-project/uyuni/tree/master/testsuite)

    If something is breaking: we can try to fix it, but the main idea is research how supported it is right now. Beyond that it's up to each project member how much to hack :-)

    • If you don't have knowledge about some of the steps: ask the team
    • If you still don't know what to do: switch to another distribution and keep testing.

    This card is for EVERYONE, not just developers. Seriously! We had people from other teams helping that were not developers, and added support for Debian and new SUSE Linux Enterprise and openSUSE Leap versions :-)

    Pending

    FUSS

    FUSS is a complete GNU/Linux solution (server, client and desktop/standalone) based on Debian for managing an educational network.

    https://fuss.bz.it/

    Seems to be a Debian 12 derivative, so adding it could be quite easy.

    • [W] Reposync (this will require using spacewalk-common-channels and adding channels to the .ini file)
    • [W] Onboarding (salt minion from UI, salt minion from bootstrap script, and salt-ssh minion) (this will probably require adding OS to the bootstrap repository creator) --> Working for all 3 options (salt minion UI, salt minion bootstrap script and salt-ssh minion from the UI).
    • [W] Package management (install, remove, update...) --> Installing a new package works, needs to test the rest.
    • [I] Patching (if patch information is available, could require writing some code to parse it, but IIRC we have support for Ubuntu already). No patches detected. Do we support patches for Debian at all?
    • [W] Applying any basic salt state (including a formula)
    • [W] Salt remote commands
    • [ ] Bonus point: Java part for product identification, and monitoring enablement