BOV89296 SUSE Best Practices Sharing Expertise, Experience and Knowledge. Christoph Wickert Technical Writer SUSE /

Transcription

1 BOV89296 SUSE Best Practices Sharing Expertise, Experience and Knowledge Christoph Wickert Technical Writer SUSE / cwickert@suse.com

2 AGENDA The SUSE Documentation Team SUSE Best Practices Open Source Tools for Open Source Documentation The Publishing Workflow How to Contribute

3 What on Earth are You Doing?

4 Classic Documentation Available from SUSE website:

5 Classic Documentation Overview Official SUSE product documentation Release Notes Deployment, Administration, User Guides Quick Starts, Tuning Guides Translated into different languages

6 Reference Guides and Manuals How You Can Contribute Report a bug Provide comments and feedback

7 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

8 SUSE Documentation Team, how do you define Whitepapers?

9 Whitepapers Technical Whitepapers Business Whitepapers Doc team can help Done by Marketing Collaborate/Feedback: Contact your Account Executive or Marketing Team

10 And what are the SUSE Best Practices?

11 FreeImages.com/Michel Meynsbrughen

12 FreeImages.com/Mark Normand

13 FreeImages.com/Gittan Noren

14 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

15 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

16 SUSE Best Practices Content Why reinvent the wheel? SUSE doc team is not providing content. Subject matter experts share their expertise.

17 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 inhouse, they know what they have implemented

18 SUSE Best Practices What We Can Do For You Communication Coordination Editing Proof-reading Porting Publication Promotion FreeImages.com/Stefan Wagner

19 SUSE Best Practices Different Formats HTML, Single HTML, epub, PDF

20 What Tools Are You Using?

21

22 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

23 Tools DocBook XML Editors Many different editors available, many of them open source: Vim Emacs Jedit Jaxe Oxygen Sublime Xerlin Xtrans It is just a matter of preference

24

25 Tools DAPS Output Formats

26 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

27 Tools Style Guide

28 Tools Style Checker Stylechecker Checks whether the SUSE Styleguide guidelines are followed / Package suse-doc-style-checker

29 Tools Git Version Control Git GitHub GitFlow

30 Tools GitHub Repository

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

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

33 Workflow How You Can Contact Us Reach out to SUSE directly Send an with details to Contact your SUSE Account / Partner Executive Send an to Meike Chabowski chabow@suse.com Use Bugzilla to submit a topic

34 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 We take them all! FreeImages.com/Jurgen Nijhuis

35 Should I really contribute?

36

37 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

38 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

39 Help us lift the treasuries for your own benefit FreeImages.com/novitas

40 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 Disclaimer This 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 thirdparty trademarks are the property of their respective owners.