You might have heard me emphasizing it several times: in my view, documentation is an essential part of a product, above all when it comes to software. Most software tools just and only become usable thanks to comprehensive documentation. If you work in an IT department and you are responsible for operative and productive environments and smooth processes, this impacts your daily work and probably also your businesses success. Documentation makes information easily accessible, helps new users learn quickly, simplifies the product and often results in reduced administration and support costs. For our customers, good documentation is definitely important.
In general, documentation consists of different categories. Just a few examples: There is Marketing material, such as whitepapers, brochures, data sheets, that contain valuable information. There are technical articles in professional magazines. And there is the classical reference documentation, such as guides, manuals, release notes, etc. – and – I never get tired of repeating it – my teammates are doing a phenomenal job here.
Additionally, in every organization, a lot of hidden IT knowledge and experience exists – just like treasuries that are hidden in the deep blue sea.
Our consultants, sales engineers, supporters work with our partners and customers on a daily basis to implement, strengthen and fine-tune our solutions, to find the best options how to install third party software on top of our operating system, or to get the most out of a customer’s infrastructure. An engineer might have found a certain solution to address a common problem in a repeatable manner, which is not yet documented. Infrastructure departments have to solve challenges, or already found easy ways to implement certain set ups, which might occur similarly or be helpful in a customer set up.
For every product and solution, there are subject matter experts that have profound know-how and skills. Many proof of concepts and projects have been conducted. And many of them might in big parts already be documented. But this kind of information is normally “buried” on a personal laptop, probably on a team server, but generally not publicly available for our colleagues, our partners or customers.
The purpose of the SUSE Best Practices is to change this situation, to make existing knowledge and experience available to a broader audience, and to promote it via a recognizable series of documents. Yes, with the SUSE Best Practices, we introduce a new series of documentation. But why are we doing this? The answer is easy: there is a real NEED for it. We get requests from customers, partners, and also from our colleagues, to provide more solution based information.
While the SUSE product documentation mainly guides through the installation and usage of products, the SUSE Best Practices provide installation and implementation experiences. This means a SUSE Best Practices paper describes a technical scenario or solution that is not covered by the general and extensive SUSE product documentation. Such a scenario can also include third party software and implementations (partly) done by partners.
And while the SUSE product documentation is delivered in parallel with a new product or a next version, the SUSE Best Practices usually will not adhere to newly launched products, but to products already introduced to and established in the market. Usually the scenario /solution has already been conducted in a real-life scenario at a customer’s site. It can include – but is not limited to:
- a specific, non-common (but repeatable) setup
- the installation of 3rd party software on top of a SUSE product
- the implementation of a multi-part solution
- a step-by-step procedure
- a newly tested procedure
- a proven process or methodology
This also implicates that the main content for a SUSE Best Practices paper cannot be delivered by the SUSE documentation team. We heavily rely on the know-how and operating experience of our colleagues, customers and partners, who implement solutions onsite, or provide workarounds and solutions for certain technical challenges.
And of course, we´d like to invite you, the technical experts, to contribute to the SUSE Best Practices series of documentation. Please suggest your topics, you are working on a huge variety of topics, and you know which kind of information is needed and might be from interest for others, too.
Although the content will have to come from you, we help to fine-tune the content where needed, via face-to-face conversations, phone interviews, or email conversations. We edit the content and take care of proofreading. If you don’t want to disclose your company’s name, we will make the content “anonymous”. For the publication of the documents, we use the official SUSE documentation workflow. To make it easy for you, WE JUST TAKE THEM ALL: no matter which format you use, no matter if you send us OpenOffice or Word documents, pure text files, PDFs, ASCII or anything else, we move the content into DocBookXML, bring it into the formal “layout” of our SUSE documentation, and make the papers available in four different formats: HTML, Single HTML, PDF and even ePub/eBook.
Finally, we publish the papers on our SUSE documentation public web page – just have a look at the papers that are already out there (btw, we are also already working on a portal for the SUSE Best Practices)! And we promote and market the papers via diverse channels and activities (social media, blogs, marketing campaigns where appropriate, news briefs, events, etc …).
So, why reinvent the wheel?
- Share your experience – AND benefit from the knowledge of others.
- Respond to new requirements (e.g. in the field of cloud or storage) much quicker, get faster time to solution – AND increase your own customer’s satisfaction.
- Learn faster about new technologies and how to implement them yourself – AND teach others.
- 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
- Save time and effort by capitalizing from existing documentation of similar setups, in reproducing scenarios that already have been implemented by others – AND help others to reach the same goal.
- Get access yourself to much more detailed additional information – AND be a vital part of the Open Source community: we share all documentation under the GFDL.
- AND finally: get a cool limited edition SUSE gift for your contribution.
If you want to propose a topic and contribute to a SUSE Best Practices paper, just reach out to us! You can write an email to the documentation team at email@example.com, or send an email directly to me (firstname.lastname@example.org) with your proposal. Another option is to contact your Account or Partner Executive – they know how to find us :-).
Disclaimer: The text at hand has not been reviewed by a native speaker. If you find typos, please send them to me (email@example.com) – or if you like them, just keep them :-).