IA Project Phase II Content Specification

Phase II - Content Specification

Table of Contents

1. Content Specification

1. Content Specification

In Phase 2, as you gain more information about the project, you evaluate your earlier Information Plan to decide if it is still accurate in predicting project scope … in Phase 2 you move on to a more detailed and updated plan instead, updating the original Information Plan in the process.

1.1. Goals and Objectives for the Publication

The current publications contain a significant amount of information, across four books. However, over time, the books themselves have become disorganised and content is now broken up in sometimes unpredictable ways. This has resulted in significant duplication of content, as well as making it difficult to identify areas of missing content.

This project intends to reassess the documentation suite from a user perspective. Once the primary personas have been identified, a user task analysis will need to be performed in order to determine the best possible organisational structure for the content.

Additionally, the books need to have a good structure in order to aid eventual contributions from the Uyuni open source community. This will have an impact on the way the books are developed, as there is a requirement to maintain both community and enterprise versions of the same documents.

While it is noted that the eventual goal of this suite is to have it operate under a fully reusable topic-based system, following the Every Page is Page One model developed by Mark Baker, this is somewhat outside of the scope of this project. If this project is successful, however, moving to this documentation model will be significantly easier in the future.

1.2. Description of the Product or Process

SUSE Manager is an open source infrastructure management tool, which can be used to manage a range of Linux systems (physical or virtual, SUSE or Red Hat). It is primarily focused on simplifying infrastructure management, through a range of tools that provide automation, batch processing, and scripts. The primary target audience for the product is system administrators who, without SUSE Manager, would be handling large numbers of systems manually.

1.3. Usability Goals of the Publication

The primary complaint of the current documentation is that it is confusing to navigate. Therefore, the primary goal of this project is to reorganise the content in such a way that it makes more logical sense to a new reader. In order to do this, we need to carefully address the primary use cases of the primary audience types, and determine a suitable structure across the documentation suite.

The final product should achieve these over-arching usability goals:

Potential users can find general information on how the product could be used in their environment (use cases)
Concepts must be clearly explained
New users can easily find an installation path that suits them (proof-of concept vs production installation)
There should be a clear differentiation between tasks that need to be completed once only (configuration or first run tasks), and those that need to be performed regularly, or on an ad-hoc basis (as ongoing maintenance or management)
Internal users should be able to follow all tasks when assisting customers either in person or remotely (for example, tasks should be able to be easily relayed over the telephone)
Advanced users should be able to easily locate reference material as quick reminders when necessary (structure and search)
Updates to the documentation should be able to be pushed regularly and with minimal technical overhead
The content should be cohesive and consistent throughout the suite (use of examples, writing style, language, etc)
The content should be accessible by screen readers (captions in images, etc), and in plain English (appropriate for translation)

1.4. Audience Profile

Interviews have been conducted between 5 & 10 October 2018. Notes from those interviews can be located as separate files within this planning repository.

A survey was sent out on 9 October 2018, for completion by 19 October 2018. A document summarising the results of that survey can be located as separate files within this planning repository. Alternatively, view the dashboard of results on Survey Monkey: http://www.surveymonkey.com/stories/SM-K3BZLJM/

Table 1. Updated User Profile
User	Technical Ability	Linux Ability	Education	Reading conditions
System Administrators	High	Moderate	Tertiary	Indoors, connected
Sales	Moderate	Low-Moderate	Tertiary	Mobile
Support Engineers/Consultants	High	High	Tertiary	Mobile

1.5. User/Task Matrix

This matrix examines each identified user task, and evaluates the probably that each user type will perform each task (High, Medium, Low).

Table 2. User/Task Matrix
Task	System Admins	Sales	Support
Product Research	Low	High	Medium
Planning for installation	Medium	Low	High
Creating an account/signing up with SUSE	Medium	Low	Low
Installing base software	High	Low	High
Installing clients	High	Medium	High
Updating base software	High	Low	Medium
Managing clients	High	High	High
Managing base software	High	High	High
Other client administration tasks	High	High	High
Troubleshooting	Low	Low	Medium

Scoring a 3 for High, 2 for Medium, and 1 for Low, the critical paths, therefore, are (in order):

Managing clients by all users (9)
Managing base software by all users (9)
Client administration by all users (9)
Installing clients by admins and support (8)
Installing base software by Support (7)
Updating base software by admins (7)
Planning for Installation by Support (6)
Product Research by Sales (6)

1.6. Annotated Outline of the Publication Subsections

1.6.1. Installation Guide

What is SUMA? (high level)
Components (how it fits together- include architecture diagram/s)
- Server
- Proxy
- Clients
- Salt
- Database
Install SUMA
- IBM zSystem
- Power
- …
Install Proxy
Automated Installations
- Bootstrap
- Unattended
Security
- Kubernetes
- Networking