Continuing from ALM Rangers – Raising the Quality Bar for Tooling (Part 1) we introduce the new documentation style for ALM Ranger documentation. It is another initiative owned by Michael Fourie who has done a phenomenal job to turn the quality dial another notch.
Extracted from 01 — TEMPLATES README.docx … we would not expect any less from Mike than document each template in concise and professional manner. What will be evident to all seasoned ALM Rangers is that we are moving from a mountain of templates to seven (7) templates
We are introducing new templates using a fresh modern new look influenced by modern UI themes and Office 2013. This new look provides both enthusiasm and encouragement to the authors as well as the readers. Along with the new template we are providing guidance and tips to provide concise documentation which can be more readily consumed by our target audiences.
ALM Rangers Guide.dotx
This will become the main guidance document for a project and contains detailed styles and guidance. Please review this in detail
This is the same as the ALM Rangers Guide.dotx but has no styling and guidance tips. It is to be used by contributors to work on their specific tasks and then the lead can combine the content into the main guidance document.
This is the template for a Hands-on Lab
This is the template for a one to three page quick reference guide to your project.
Use this if you need an ad hoc presentation or for a stand-up.
Use this to kick-off your project.
Use this to show the ALM Rangers what your team has produced thus far.
What are some of the main changes?
The screenshots in this section are from the latest and greatest Branching and Merging Guide. See @@ for more information.
The header page on the left introduces the crisper and modern UX look & feel. An arbitrary page from the guide is shown on the right continues the crisp and professional look and feel, while the NOTE, WARNING and other information boxes are more prominent.
Table of Contents is “Crisper”
The age of pages and pages of table of content (TOC) are over. The new template limit the TOC to heading two levels, which usually limits it to one page and makes it much easier for the user to find the relevant sections.
Introduction is one “digestible” page
The introduction of the document, the ALM Rangers, the contributors and “what’s new” is consolidated on one page. A general theme is to deliver more professional, easier consumable and much crisper documentation with the dream of “delivering less, better”.
Table of Figures, Tables and Code move to the end
The resources, references and tale of figures, tables and code which often cluttered the beginning of guides, have been moved to the end of the documentation. Hopefully it will be less distracting in this location, yet be available for those that make us of this information.
We need your “candid” feedback
We need your candid feedback on both the tooling quality and the documentation style changes, so that we can continue improving and turning the quality dial from to .