Post on 16-Oct-2019
BOV1058
SUSE Best PracticesSharing Expertise, Experience and Knowledge
Meike Chabowski
Documentation Strategist
SUSE / meike.chabowski@suse.com
2
Who Am I ?
Master of Arts in IT (Italian and Theater & Mass Media)
=> Ended up in real IT (~25 Years)
~19 years at SUSE
• ~16 in Product Marketing• ~3 in Documentation
Documentation Strategist
• Find new channels for documentation• Standardize documentation• Introduce new series
3
Agenda
● Meet the Docs
● How we work
● What are the SUSE Best Practices
● Contribute!
Photo by Susan Yin on Unsplash
Photo by Jonas Jacobsson on Unsplash
4
Meet the Docs
5
Who We Are
6
What We Want To Achieve
7
Pillars of Documentation
SUSE Best Practices
Editing & Publishing
Whitepapers
Supporting
Product Documentation
Writing
ToolchainDeveloping
8
And We Are Doing Even More(but not a focus for this presentation …)
● Software Translation Coordination
● Technical Trainings (internal and external)
● Articles and Blogs
● Presentations and Representation
9
How We Work
10
Workflow
Overstrained Now?
12
Request Documentation: Jira, Bugzilla, DocComments
Documentation request via email:
doc-team@suse.com
13
Evaluate, Accept, Organize: Trello
14
Create Content / Research
● Original requester & developer to provide basic information
● Interview subject matter experts, developers
● But more often than not: download software, set up virtual machines, install the work-in-progress products and document from there
15
Write: In DocBook XML
DocBook• Semantic markup language for tech
documentation• Based on the eXtensible Markup Language
(XML)• Defines content in semantic way similar to HTML• Open standard maintained by OASIS• Used by many Open Source Projects • Written as a schema which fulfills two tasks:
guided editing and validation• http://docbook.org/
We evaluated alternatives, but none of them fully meets our requirements.
AsciiDoc
Markdown
ReStructuredText (reST)
Textile
Almost Free Text
Almost Plain Text
Txt2tags
…
16
Write: With Editor of Choice
Classic Programmer Paintings: “Emacs vs. Vim" (Goya, 1820–1823 Oil mural transferred to canvas)
17
Write: According to SUSE Style Guide
18
Create Infrastructure: GIT* (Hub, Lab, Flow)
20
Format: Via XSLT Style SheetsDefine the layout for SUSE documentation• Books: Manuals, Guides• Articles: Quick Starts, SUSE Best Practices, Shorter Guides• HTML pages (for all kind of documentation)
Book/Manual (Guide) Article (SBP)HTML
https://github.com/openSUSE/suse-xsl
21
Build, Review, Edit, Build: with DAPS
Build the document with DAPS:• Validate file for correct links, references,
spelling, etc...• Build output format (PDF, HTML, ePub, ...)
Review and editing period• Quick proof of output formats• Peer review• Technical expert review
Repeat Steps for Quality Assurance• Perform spell check and link check via DAPS
(once again)• Build output format (once again)
To write is human, to edit is
divine(Stephen King)
22
Perform QA: Style Checker
Stylechecker• Checks whether the
SUSE Style Guide guidelines are followed
23
Workflow Repeated
24
What Are the SUSE Best Practices?
25FreeImages.com/Michel Meynsbrughen
Our IT World
26FreeImages.com/mark normand
Hidden Treasuries
27FreeImages.com/Gittan Noren.
Lift Treasuries
28
SUSE Best Practices - Why
Why a separate series • There is a NEED• Make existing knowledge and experience publicly
available to a broader audience• Promote it via a recognized series of documents
What makes SUSE Best Practices different• SUSE product documentation: mainly guides
through SUSE software installation and usage• SUSE Best Practices: provide installation and
implementation experiences
29
SUSE Best Practices – What
Content:• Specific setup at a customer site• Installation of 3rd party software • Implementation of a multi-part solution• Step-by-step procedures• “How-to” • Do’s and Dont’s • Hints, Tips and Tricks
Focus• Describe technology / technical scenario / solution not
covered by SUSE product documentation• Can include third party software and implementations• Usually about products established in the market
30
SUSE Best Practices – Content
Why Reinvent the Wheel?
SUSE doc team is not providing content.
Subject matter experts share their expertise.
Photo by Arvind Thangli on Unsplash
31
SUSE Best Practices – YOU Are the Experts!
Propose topics• You are working on
solutions (together with SUSE contact)
• You are expert for a certain technology
Share your experience• Be inspired by the open
source spirit – not only for coding but also for documentation
32
SUSE Best Practices – What We Do For You
Coordination
Communication
Content finalization
Content Editing
Photo by John Hult on Unsplash
33
SUSE Best Practices – What We Do For You
Porting
Proof-reading
Publication
Promotion
Photo by Jason Rosewell on Unsplash
34
SUSE Best Practices Different Formats
• HTML, Single HTML, ePub, PDF
35
Should I Really Contribute?
36
37
Send Your Content
We don’t care about the format of your content – because we take care of it!
• ASCII• XML• LibreOffice or Word Documents• PDFs• Pure text files• Email
FreeImages.com/Jurgen Nijhuis
WE TAKE THEM ALL
38
Collaboration Made Easy – Edit in Git
39
SUSE Best Practices – What’s in For You?
● Share your experience – AND benefit from knowledge of others
● Get faster time to solution – AND increase your customer’s satisfaction
● Create joint high quality technical papers – AND use them for your own purpose and distribution
● Use our promotional machinery – AND let us help you to increase your visibility
AND● Get a cool limited edition SUSE gift
FreeImages.com/Aleš Čerin
40
Use Bugzilla to submit a topic
How You Can Contact Us
Reach out to doc team– Send an e-mail with
details to
doc-team@suse.com
– Send an e-mail to Meike Chabowski chabow@suse.com
– Contact a SUSE Account / Partner Executive
https://www.suse.com/documentation/suse-best-practices/
41
Help us lift the treasuries – for your own benefit
42
Meet the Docs @SUSECON
● Doc Day
– Friday April 5th, 9am – 6pm (room Midtown 1) – Get together at 6 pm
– Attendance is free and open for everyone – but register/let us know for org reasons
– Topics: SUSE Linux Enterprise Server, OpenStack Cloud, Container Technologies/Docker
• Developers Lounge Booth
– Office Hours
– Come talk to us! • Give feedback• Fill out survey • Take the chance to win giant chameleon and other cool prizes
● Developers Lounge Theater Presentations
43
Thank you very much for your attention!
Questions? meike.chabowski@suse.com
Follow me on Twitter@MChabowski
Blogshttps://www.suse.com/communities/blog/?s=chabowski
45
Unpublished Work of SUSE LLC. All Rights Reserved.This work is an unpublished work and contains confidential, proprietary and trade secret information of SUSE LLC. Access to this work is restricted to SUSE employees who have a need to know to perform tasks within the scope of their assignments. No part of this work may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of SUSE. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability.
General DisclaimerThis document is not to be construed as a promise by any participating company to develop, deliver, or market a product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. SUSE makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. The development, release, and timing of features or functionality described for SUSE products remains at the sole discretion of SUSE. Further, SUSE reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All SUSE marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.