-
Notifications
You must be signed in to change notification settings - Fork 34
SUSE Manager IA Overhaul
Links to phases:
Links to supplementary material:
This document provides the reasoning behind the suggested changes regarding the Information Architecture(IA) rework to SUSE Manager/Uyuni documentation. It also offers Lana and I, a way of tracking and planning these changes within the coming months.
The time has come to:
Make SUSE Manager/Uyuni deeper and wider!
SUSE Manager 4.0 Kickstart 2018
Around a year and a half ago Klaus and I met to discuss the former marketing/accepted titles "Best Practice" and "Advanced Topics" and found them lacking due to abstraction. Some of our observations included the following:
-
Customers have difficulties searching for topics as these two ideas are vague. (And we do not offer context based search…)
-
Furthermore what rule specifies that a topic is an "Advanced Topic" or a "Best Practice"?
-
This makes placement of topics in these books complicated and arbitrary.
After our discussion I spent the afternoon going over individual documents/sections organizing topics into more specific book names (Getting Started, Deployment and Installation, Administration, Reference) and sent these via email to Klaus. As often occurs in development these observations/suggestions were necessarily pushed back to a later date due to a lack of time and release constraints around feature development.
Enter Lana Brindley, our new docstar! After beginning at SUSE (Early June) she recognized the state of {productname} IA within 4 weeks of her start date during a Hackweek critique and brought these observations to our team’s attention. Her work is well defined and will be the foundation for these IA changes. The suggested changes will greatly improve documentation and therefore should be pursued relentlessly as an epic. Lana’s original Hack Week presentation can be found here: [HackWeek-SUMADocsIA.pdf]
The goal of this much needed IA rework is to clear up our book structure, clearly define individual titles of documents(representing their slugs in the webui/online docs) and to create a set of guidelines for naming single source content in the future. An additional concern should be how our target audience is using the product. These user tasks should be ordered and grouped logically into parent/child relationships.
-
Target audience and the approach taken by them to begin working with SUSE Manager/Uyuni
-
Tasks required by our audience to be successful
-
Topics should be ordered by task
-
Clumping topics into the correct parent container
-
Every page is page one (Perhaps we can try to make this reality?)
ImportantSuggested changes will have a large effect on how we sort out the differences between Uyuni and {productname} our enterprise product.
In order to ensure we are making changes that work generally (not just those that 'seem right' to us at this moment in time), we will be following a well-established framework to guide our work. JoAnn Hackos is a well-known and respected author on technical documentation project management. Her book "Managing Your Documentation Projects" is considered a gold-standard approach to project management for documentation tasks, and has been used by commercial documentation teams around the world for many years. This approach uses a five phase model, and dedicates 30% of the project to planning tasks, in order to ensure the final product is of a high standard.
For those of you with a Microfocus supplied Safari Books Online account you can access this book here:
-
Information Plan [PhaseI_InfoPlan.adoc] (10%)
-
Content Specification [PhaseII_ContentSpec.adoc] (20%)
-
Implementation [PhaseIII_Implementation.adoc] (50%)
-
Production [PhaseIV_Production.adoc] (19%)
-
Evaluation [PhaseV_Eval.adoc] (1%)
Milestone | Start | End |
---|---|---|
Phase 1 |
6 Aug 18 |
31 Aug 18 |
Phase 2 |
3 Sep 18 |
2 Nov 18 |
Phase 3 |
5 Nov 18 |
26 April 19 |
Phase 4 |
29 April 19 |
28 June 19 |
Phase 5* |
1 July 19 |
26 July 19 |
Note that Phase 5 is an evaluation phase, and can be completed after publication. This plan assumes an end-June 2019 release date.
Content will be moved to wiki
Who are our targets, how do we ensure their success? Current known end-users are the following.
-
Administrators
-
Sales and Field Engineers
-
Chief Information Officers(CIO)
-
Developers/QA
-
New Uyuni Open Source Community (Developers/Engineers/Administrators)
From our list of end-users we can reliably conclude therefore that we need to include relevant knowledge at a level greater or equal to that of a junior Administrator.
Important
|
We should probably consider verifying these with Jeff, Michael Brookhuis, Torsten, and Klaus. (Even if it was already done @ 2.1) |
Important
|
Expect Change
These final book names are subject to change. The final names will be selected and based on a complete IA study based on "Managing Your Documentation Projects" by JoAnn Hackos. The following names will be used temporarily for clumping current documents |
The Getting Started guide begins with a product description, obtaining {productname} and how to connect to SCC, hardware and software requirements and network requirements. It covers creating a test installation with KVM and SLES and walks a user through installation steps, {productname} setup via yast and connecting clients that will be managed. It ends with more resources and where one can proceed next.
The Installation Guide covers all things having to do with deployment of any kind. These should include: bare metal installation, virtual deployment, and proxy installation. It should provide access to all known installation methods including initial configuration. These installations should include SUSE Manager Server, SUSE Manager Proxy, and Uyuni Server and Proxy. Installation should be broad covering a wide range of computer architectures types to include s390, x86_64, and IBM power.
The Administration Guide covers all things having to do with Administration of the {productname} server including the use of third party applications.
The Salt Lab should cover a basic introduction to Salt, moving up the knowledge ramp advancing throughout. Architecture in relation to {productname}, configuration management, remote execution, event-driven infrastructure, and salt essentials should be discussed.
There should be a salt lab containing tutorials for working directly with the command line, and examples from the WebUI state editor. Some topics would be: Grains, pillar data, targeting, runners, YAML, State modules, running commands, execution modules, beacons etc.
Salt is a huge topic and therefore will require extensive research and testing. However this would be of great benefit to our customers as it would directly relate to {productname}. (Some of these topics already exist in the Salt GS, however I have a number of ideas to help improve how our customers view us in terms of quality.)
See the Administration IA document, it includes the Salt Lab document within a set of books. As one alternative approach.
The WebUI and Reference Manual will continue to be developed, however it describes the interface using direct comparison. Therefore we will only be required to make modifications to references to other books. It will remain as is while maintaining its course with feature development.
This document may find a home in the users/administration guide
Setup and Build
- Setup rbenv and Ruby
- Install nvm
- Install Antora
- Install Asciidoctor Gems
- Building the Docs
- Optional Tools
How to Publish
Publish to OBS
Publish Enterprise Docs
Publishing to Github Pages
Want to Help?
Get Started with Asciidoc
Quick Syntax Reference
Asciidoctor Writer's Guide
Asciidoctor User's Manual
Resources
YAML Documentation