Willy's Reflections - Visual Studio ALM Rangers

| Willy-Peter Schaub | Visual Studio ALM Rangers | In search of IT simplicity, quality and tranquility |

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

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

Rate This
  • Comments 5

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.

imageNew 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 Smile

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.

image

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.

image

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.

image     image

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.

image

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

image

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.

image


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 Smile to Open-mouthed smile.

The teams are image to your feedback!

  • Way cool and wicked awesome. You guys rock.

  • Love the new template!

  • Where can I find a download of the revised documentation templates?

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

  • Michael Fourie has an enlightened mind

    Thanks for that.

Page 1 of 1 (5 items)
Leave a Comment
  • Please add 6 and 6 and type the answer here:
  • Post