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)

19

Create Infrastructure: DAPShttps://github.com/openSUSE/daps

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.