Case Study: Using Confluence for Requirements and Specifications of a Consumer Electronics Device Anthony Pelosi, Magellan GPS
Nov 30, 2014
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.