Meet the latest SUSE documentation “accrual”

You might have already realized it when looking at our documentation.suse.com portal: the SUSE Best Practices (SBP) series of documentation got a new sibling—and it is growing fast! Yes, I am talking of the Technical Reference Documentation (TRD).

Under the two currently available categories Kubernetes and Linux, we have already published 50+ documents—expect more to be posted during the next few weeks.

Now you might ask: what is the difference between SBPs and TRD? It is easy to explain but takes some reading time 😁, so be prepared.

SUSE Best Practices explained

SBPs provide reliable technical information not covered by the SUSE product documentation. They consolidate the scattered pieces of information, tips and hints, technical notes, and “tribal knowledge” from real-world implementations of and user experience with the SUSE portfolio, which contribute to a successful setup and maintenance of an organization’s IT environment. Since SBPs are topic-oriented and solution-based documents, they should serve as an addition to the user reference guide.

SBPs may cross product boundaries, and may incorporate discussion related to non-SUSE products, where common integration topics crop up. They can include (but are not limited to):

• a specific, non-prevalent but repeatable setup
• the installation of third-party software on top of a SUSE product
• the implementation of a solution consisting of several products or technologies
• a step-by-step procedure
• a newly introduced but proven process or methodology

SPBs aim to save time as they use existing knowledge for further replication. Thus, they should be replicable and adaptable, and they should be sustainable and easy to update. The content of an SBP is NOT written by the documentation team, but by subject matter experts. And these subject matter experts are not necessarily SUSE employees. In fact, we not only welcome but encourage contributions from customers as well as implementation and technology partners. The documentation team then edits, proofreads, finalizes, publishes, and promotes the articles.

Technical Reference Documentation explained

Technical Reference Documentation (TRD) provides recommendations and guidance for the design, implementation and configuration of SUSE products combined with components and products from the portfolio of defined hardware and software partners. The referenced solutions usually target specific scenarios and use cases, and offer a form of blueprints for those.

TRDs are currently classified into one of the following document types:

Getting Started: Basic steps to quickly and easily deploy the one layer of the referenced component of the SUSE portfolio, with generalized pointers to other required elements.

Reference Implementation: Basic steps to deploy the highlighted components of the SUSE portfolio, including generalized pointers to other layers and elements. This is considered an introductory approach and a basis for other tested variations.

Reference Configuration: Basic steps to deploy the layered stack of components from both the SUSE and partner portfolios. This is considered a fundamental basis to demonstrate a specific, tested configuration of components.

Reference Architecture: General steps to deploy and validate the structured solution components from both the SUSE and partner portfolios. This provides a consistent shareable template that consumers can leverage for similar production ready solutions, including design considerations, implementation suggestions and best practices.

Solution Stack: Validated framework guides with SUSE offerings and partner components that leverage the strengths of the combined ecosystem to address the challenges of a broad spectrum of customers.

Enterprise Architectures: Guides that address the business and IT concerns within an organization.

Technical Reference Documentation is currently owned and created by a group of SUSE experts closely collaborating with technical contacts from SUSE’s most important technology partners (IHVs and ISVs). These experts are usually Enterprise or Solution Architects, Technology Strategists, or Partner Engineers. A major part of the TRD is provided by members of the Global Solutions teams working with strategic hardware partners. Contributions to the TRD are also coming from members of the Partners & Alliances and Partner Engineering teams who cooperate with software alliance partners and ISVs. The documentation team mainly takes care of editing and publishing the documents these experts deliver.

And the Oscar goes to …

At this point, it’s time for my acceptance speech. Well—no—don’t worry! But I’d really like to highlight two very special colleagues:

Bryan Gartner and Terry Smith—THANK YOU for having taken over responsibility to deliver the content for this important new series of documentation to our ecosystem, and for being so great to work with.

Disclaimer: The text at hand has not been reviewed by a native speaker. If you find typos or language mistakes, please send them to me (meike.chabowski@suse.com) – or if you like them, just keep them and feed them.