20130305 SFAUG Confluence Case Study

Case Study: Using Confluence for

Requirements and Specifications

of a Consumer Electronics Device

Anthony Pelosi, Magellan GPS

Who Am I?Anthony Pelosi (not related to Nancy that I know

of)

Technical Product Manager of Fitness Products at Magellan GPS

Jira & Confluence user for 6 years at 3 companies

Previous Presenter at SFAUG and Atlassian Summit

This Presentation is NOTBest Practices

Introducing Latest Features

Well Polished

Attempt to Promote any Product or Service

This Presentation ISActual Case Study (may be ugly at times!)

Showing Simple Techniques in Powerful Ways

Work in Progress

Going to Inspire YOU to Present in the Future!

Start with a Dream

Followed by a Landing Page

Tip 1: Landing PageIf it takes more than a single URL to point

someone to EVERYTHING they need to know for the product, you did something wrong.

Organize the ContentPage Content: Everything on the page itselfChild Pages: parent-child folder hierarchyRelated Pages: rules based on labels (like Gmail)

Macro: Content by Label Use the “Content by Label” Macro to bring

together Pages & Blog Posts from Various Locations.

Advertise the Macro’s Criteria.

Got Files?

And Feedback?

Tip 2: Files & Feedback For ID presentations, we used a single page with

File Attachments and Feedback as Comments.

Much better than passing back Files and Feedback over email.

If someone sent a File over email, I added to the Page, added a Comment with my Feedback, and Replied to the email with a link to my Comment.

Macro: AttachmentsUse the Attachments Macro to reduce the need

to go to “Tools > Attachments”.

Set the “Allow Upload” Parameter to True

Pages with Same Format?

Tip 3. Use TemplatesFor Software Features, we created a Page for

each Feature.

Each Page has Table of Contents, Version History, Overview, Requirements, Specifications, etc.

Use Templates to ensure consistency across pages.

Macro: Table of ContentsStart Pages with the Table of Contents Macro.

Macro: Version HistoryFollowed by the Version History Macro to show

the most recent page edits.

Requirements in Spreadsheet?

No Problem

Tip 4: Embed Spreadsheets

For Software Requirements, we embedded a Google Spreadsheet exported as an XLS file.

Why didn’t we choose Confluence Tables?Familiar, Faster & Easier to EditAllows for Simultaneous Contributors (Google Doc)

One file attachment, embed anywhere

Split up into different Sheets by category/feature

Macro: ExcelUse the Excel Macro to embed an XLS file.

Specify the file as “page^attachment”.

Specify the Sheet.

Constant Referenceswithin Documentation?

Tip 5: Link toPages and Anchors

Referencing UI Components, Variables, etc. and other well defined entities using Text was sloppy

Referencing with Links forces you to be consistent, organized, and document in a modular fashion (the developers will respect you!)

Use Headers (ex., “h3.”) or Anchor Macro to create Anchors

Link to Anchors using “pagename#anchorname”

Macro: AnchorUse the Anchor Macro when it is not convenient

to use a Header to create an Anchor (for example, to create a reference to a row in a table)

Go With the Flow

Tip 6. Flow ChartsFlow Charts help express written requirements

and specifications visually.

Feeling Wired?

Tip 7. WireframesCreate Wireframes to represent both the

Generic Specifications and Examples of those Specifications.

Mercy!I could go on for hours, but that’s it for now.

Simple techniques can be powerful when used in a well thought out, methodic manner.

Questions?

AppendixJust in Case for Q&A!

All Requirementsin a Single Sheet?

You can use Filters to make a Sheet for each feature using a subset of the Master Sheet.