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)
Looking for hackers with the skills:
language documentation documents non-techies techies everyone publishingdocuments documentationtoolchain meetthedocteam
This project is part of:
Hack Week 21
Activity
Comments
-
-
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.
-
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"... ;)
-
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 ....
... And if I can learn DocBook, everybody else can, too 
Reply to chabowski
****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 ....
... And if I can learn DocBook, everybody else can, too
# A First Level Header ## A Second Level Header Use one asterisk to *emphasize* Use two asterisks for **strong emphasis** - Use hyphens - for unordereed - lists This is an [link to example.com](http://example.com/) This is an image  This is a user link @hans This is a project link hw#some-cool-title
-
-
-
over 2 years ago by gdsouza | Reply
Will the sessions be recorded and available later?
-
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.
-
-
-
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.
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.
-
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!!
-
-
over 2 years ago by Monzicle | Reply
Hi, I am interested in session 1-5 and session 8. Complete newbie but I am curious
-
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!
-
-
over 2 years ago by chabowski | Reply
Hi Monica, very cool! I am about to reply to you directly on your email
. 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! -
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. :)
-
-
over 2 years ago by chabowski | Reply
Thank you all for your contributions and support of the project - we had a lot of fun!
Reply to Nycticorax
Was a toll! Thanks for organizing this!
# A First Level Header ## A Second Level Header Use one asterisk to *emphasize* Use two asterisks for **strong emphasis** - Use hyphens - for unordereed - lists This is an [link to example.com](http://example.com/) This is an image  This is a user link @hans This is a project link hw#some-cool-title
-
Reply to rainerkoenig
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.
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.
# A First Level Header ## A Second Level Header Use one asterisk to *emphasize* Use two asterisks for **strong emphasis** - Use hyphens - for unordereed - lists This is an [link to example.com](http://example.com/) This is an image  This is a user link @hans This is a project link hw#some-cool-title
Reply to Monzicle
Hi, I am interested in session 1-5 and session 8. Complete newbie but I am curious
# A First Level Header ## A Second Level Header Use one asterisk to *emphasize* Use two asterisks for **strong emphasis** - Use hyphens - for unordereed - lists This is an [link to example.com](http://example.com/) This is an image  This is a user link @hans This is a project link hw#some-cool-title
Reply to chabowski
Hi Monica, very cool! I am about to reply to you directly on your email . 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!
# A First Level Header ## A Second Level Header Use one asterisk to *emphasize* Use two asterisks for **strong emphasis** - Use hyphens - for unordereed - lists This is an [link to example.com](http://example.com/) This is an image  This is a user link @hans This is a project link hw#some-cool-title
Similar Projects
Uyuni developer-centric documentation by deneb_alpha
Description
While we currently have exten...
Testing and adding GNU/Linux distributions on Uyuni by juliogonzalezgil
Join the Gitter channel! [https://gitter.im/uy...
ddflare: (Dyn)DNS management via Cloudflare API in Kubernetes by fgiudici
Description
[ddflare](https://github.com/f...