SUSE Manager IA Overhaul

Links to phases:

• Phase I - Information Plan

• Phase II - Content Specification

• Phase III - Development

• Phase IV - Implementation

• Phase V - Evaluation

• Maintenance

Links to supplementary material:

• Interview 1

• Interview 2

• Interview 3

Introduction

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!

— S.E. Don Vosburg
SUSE Manager 4.0 Kickstart 2018

Why a Rework?

Titles Matter

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.

Every Child Needs a Home

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.

A Star is Born

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]

IA Rework Goals

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.

Information architecture Process

• 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?)

  Important

  Suggested changes will have a large effect on how we sort out the differences between Uyuni and {productname} our enterprise product.

Framework

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 Development: Managing Your Documentation Projects, Portfolio, and People

Planning Documents

Google Spreadsheet for Doc IA

1. Information Plan [PhaseI_InfoPlan.adoc] (10%)

2. Content Specification [PhaseII_ContentSpec.adoc] (20%)

3. Implementation [PhaseIII_Implementation.adoc] (50%)

4. Production [PhaseIV_Production.adoc] (19%)

5. Evaluation [PhaseV_Eval.adoc] (1%)

Milestones

Table 1. Overview of Project Schedule and Major Milestones

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.

Target Audience

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)

Preliminary Distribution of Content

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

Getting Started Guide

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.

• Getting Started IA Rework Document

Installation Guide

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.

• Installation IA Rework Document

Administration Guide

The Administration Guide covers all things having to do with Administration of the {productname} server including the use of third party applications.

• Administration IA Rework Document

The Salt Lab

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.)

• Salt Lab IA Rework Document

See the Administration IA document, it includes the Salt Lab document within a set of books. As one alternative approach.

Documents Excluded from the IA Rework (Perhaps)

WebUI Reference Manual

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