Introduction

The guidance plugin provides a set of macros use to facilitate the usage of the DO, CONSIDER, AVOID, and DO NOT convention made popular in Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Krzysztof Cwalina and Brad Abrams. The macros try to provide the ✔ and the ✘ glyphs as a unicode font character that scale perfectly; however, under depending on the plugin configuration circumstances it will provide a raster image instead

Nice rendering in HTML, PDF and Word

Thee macro has a configuration page which can be accessed from the Confluence Add-on manager. In the configuration the Confluence Administrator can decide how the macro will render the glyph (as a unicode character or a raster image) for various output formats. Experimentally, the default pdf output does not render the unicode font characters correctly so the default for that format is raster.

Features at a Glance

Features in Detail

Guideline Inline

Description

This macro inserts the glyph and text inline with the rest of the text. In the editor, it will simply show a graphic with the text.

Usage

Insert the Guideline (Inline) macro. Click on the macro and select the guidance term to be used. Alternatively, one can press the edit button and select the guidance term from the dropdown.

Purpose

This macro is intended for inserting the text prior to a short sentence or paragraph. It is a bit easier to read in the e

Guideline Block

Description

This macro inserts the glyph and text in a block with the rest of the text. If the block of text starts with one of the guidance terms (Do, Consider, Avoid or Do Not) and the Guidance macro parameter is set to auto, the macro will automatically insert the appropriate glyph and bold the text. If the macro's Guidance Parameter is set to auto and the text does not start with one of the terms, an error message and alert will be shown. If the guidance term is not set to auto, the macro will insert the appropriate text. If the text also starts with the guidance term, the text will not be rendered twice.

Usage

Insert the Guideline (Block) macro. While the guidance term can be explicity set, the recommended usage is to type the guidance term into the start of the body. This make is more readable in the editor.

Purpose

This is the appropriate macro to use for multi-paragraph guidance descriptions. All of the text will be indented for the guidance term giving the reader a visual clue that it all belongs to one rule.

Do, Consider, Avoid and Do Not Macros

These are shortcuts to the block guideline macro where the guidance term is fixed to the name of the macro.

Home