BOV89296

SUSE® Best PracticesSharing Expertise, Experience and Knowledge

Christoph Wickert

Technical Writer

SUSE / cwickert@suse.com

AGENDA

The SUSEDocumentation Team

SUSE Best Practices

Open Source Tools forOpen Source Documentation

The Publishing Workflow

How to Contribute

What on Earth are You Doing?

Classic Documentation

Available from SUSE website: https://suse.com/doc/

Classic DocumentationOverview

Official SUSE product documentation• Release Notes

• Deployment, Administration, User Guides

• Quick Starts, Tuning Guides

• Translated into different languages

Report a bug

Reference Guides and ManualsHow You Can Contribute

Provide comments and feedback

And We Are Doing Even More

● Software Translation Coordination

● Technical Trainings (internal and external)

● Articles and Blogs● Presentations and

Representation

… but not a focus today

SUSE Documentation Team,how do you define Whitepapers?

Whitepapers

Technical Whitepapers• Doc team can help

Business Whitepapers• Done by Marketing

Collaborate/Feedback: Contact your Account Executive or Marketing Team

And what are the SUSE Best Practices?

FreeImages.com/Michel Meynsbrughen

FreeImages.com/Mark Normand

FreeImages.com/Gittan Noren

SUSE Best Practices

What are SUSE Best Practices• SUSE product documentation: mainly guides through SUSE software

installation and usage

• SUSE Best Practices: provide installation and implementation experiences

Why a new series • There is a NEED

• Make existing knowledge and experience publicly available to a broader audience

• Promote it via a recognized series of documents

SUSE Best Practices – In Detail

Scenario has been implemented at customer's:• Specific setup

• Installation of 3rd party software on top of a SUSE product

• Implementation of a multi-part solution

• Step-by-step procedure

Focus / Content• Describe technical scenario / solution not covered by SUSE

product documentation

• Can include third party software and implementations

• Usually about products established in the market

SUSE Best Practices – Content

Why reinvent the wheel?

● SUSE doc team is not providing content.

● Subject matter experts share their expertise.

SUSE Best Practices – YOU Are the Experts!

Propose topics• SUSE and you are

working together on solutions

• Our experts are supporting you

● Share your experiences

• Be inspired by the open source spirit

• You have the experts in-house, they know what they have implemented

SUSE Best Practices – What We Can Do For You

● Communication

● Coordination

● Editing

● Proof-reading

● Porting

● Publication

● PromotionFreeImages.com/Stefan Wagner

SUSE Best Practices Different Formats

• HTML, Single HTML, ePub, PDF

What Tools Are You Using?

Tools – DocBook XML

DocBook Is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation

DocBook XML• Based on the eXtensible Markup Language (XML)

• Defines content in semantic way similar to HTML

• Written as a schema which fulfills two tasks: guided editing and validation

• http://docbook.org/

Tools – DocBook XML EditorsMany different editors available, many of them open source:• Vim

• Emacs

• Jedit

• Jaxe

• Oxygen

• Sublime

• Xerlin

• Xtrans

• …

It is just a matter of preference

http://opensuse.github.io/daps/

Tools – DAPS Output Formats

Tools – SUSE XSLT Stylesheets

Define the layout for SUSE documentation– Books: Manuals, Guides

– Articles: Quick Starts, SUSE Best Practices, Shorter Guides

– HTML pages (for all kind of documentation)

Package: suse-xsl-stylesheets

Book / Manual Article HTML

Tools – Style Guide

Tools – Style CheckerStylechecker• Checks whether the SUSE

Styleguide guidelines are followed

• https://gitorious.org/style-checker/

• Package suse-doc-style-checker

Tools – Git Version Control

Git

GitHub

GitFlow

Tools – GitHub Repository

Now you’ve heard about the tools, but how does the Workflow look like?

Workflow

(for documentation projects, applies in general also to the SUSE Best Practices)

Use Bugzilla to submit a topic

Workflow – How You Can Contact Us

Reach out to SUSE directly– Send an email with details to

doc-team@suse.com

– Contact your SUSE Account / Partner Executive

– Send an email to Meike Chabowski chabow@suse.com

Workflow - 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!

Should I really contribute?

SUSE Best Practices

Propose topics• SUSE and you are working together on the solutions

• Our experts are supporting you

Share your experiences• Be inspired by the open source spirit

• You have the experts in-house, they know what they have implemented

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

FreeImages.com/novitas

Help us lift the treasuries – for your own benefit

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.