ALM Rangers – Raising the Quality Bar for Documentation (Part 2)

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.

New templates at a glance

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.

Word Templates

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

Contributor FastStart.dotx

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.

HOL.dotx

This is the template for a Hands-on Lab

Quick Reference.dotx

This is the template for a one to three page quick reference guide to your project.

PowerPoint Templates

General Presentation.potx

Use this if you need an ad hoc presentation or for a stand-up.

Kickoff.potx

Use this to kick-off your project.

ShowUsWhatYouHave.potx

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.

New Style

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 .

The teams are to your feedback!

Comments

• Anonymous
  October 17, 2012
  Way cool and wicked awesome. You guys rock.

• Anonymous
  October 17, 2012
  Love the new template!

• Anonymous
  November 03, 2012
  Where can I find a download of the revised documentation templates?

• Anonymous
  November 03, 2012
  Keith, the templates are not available for download. They are used when creating new ALM Rangers documentation and guides. See blogs.msdn.com/.../alm-rangers-ship-the-new-branching-and-merging-guide-v2-1.aspx which is the latest version of the guidance, based on the new templates. We are looking for candid feedback whether the templates are improving the content. Why you are looking for the templates?

• Anonymous
  December 14, 2012
  Michael Fourie has an enlightened mind Thanks for that.