About this article
By Terrence Caldwell, published August 31st, 2015
Successful dev teams need to be able to move fast, without sacrificing code quality. Since you can't just go out and make clones for your developers (yet...), how do you make your team faster?
Try these two tactics: first, speed up the time it takes to onboard new team members. Second, limit the amount of time your team spends searching for answers to technical problems.
Of course, you want to spend your time building awesome products and not writing docs. At the same time, you need good docs to help your team build awesome stuff. Confluence helps solve the paradox by making it easy to create and document your standard technical docs so everyone can access and contribute to them. In short order you'll be a lean, mean documentation machine.
Check out three standard technical docs that your team can create in Confluence:
Getting new people current is critical to your dev speed as well as the future success of your team.
Start new hires with a guided task list. You can add tasks to any Confluence page from the editor toolbar:
The new hire task list or 90 day plan should provide direction and useful resources. Include instructions on logging into critical systems and applications, links to important internal resources like company policies, and tasks for meeting members of the team.
Pro tip
Create one universal new-hire task list that lives in your team space. Whenever a new person starts have them copy that page and move it into their personal space. They can edit the task list to add additional tasks, as well as assign themselves due dates for tasks to be completed.
Your task list is a great resource for pointing people in the right direction. But what are you pointing them to? You'll need a handy set of how-to docs to help new hires help themselves.
Get started with our how-to blueprint – it gives you the basic layout so you can focus on adding content.
Pro tip
Label all your onboarding docs with the same label, like "onboarding", or something similar. With all your docs labelled, you can create a central repository of them using the content by label macro.
Make sure to add images, code blocks, and links to relevant web content to your page.
After you've completed your page, you'll notice the Content by Label macro at the bottom. This macro automatically pulls in all the pages in the current space with the same label.
Once the page is saved, you can see a dynamic list of pages with the same label:
These documents need to be accessible to the whole team, at all times. Here's how to put together your architecture docs in Confluence:
Pro tip
Use diagramming tools to embed architecture diagrams. There are two great add-ons available in the Atlassian Marketplace that are perfect for this: Gliffy and Draw.io. Both these add-ons give you a diagram editor right within Confluence. We use these tools as well as websequencediagrams.com for simple relational diagrams that you can attach as images.
The most important part of your architectural docs is being able to reference diagrams, components, SDKs, APIs and related docs all in one place. These documents can be as heavy or light on information as you need. At Atlassian, we put all this information in tables. Tables are easy to insert into your page, and flexible. Use the table tools menu to add and cut columns and rows, merge, and highlight cells.
Just like your onboarding content, you'll want to label all your related architectural docs to keep them organized.
The other important set of documentation you'll want to create and store in Confluence is your release process and readiness docs. These are the documents that streamline your releases and help build a culture of continuous improvement, and are probably constantly evolving as you adopt new practices to improve your process. So you'll want to make sure everyone has access to the latest n' greatest – which is exactly what Confluence was built for.
There are three key elements to your release process documents:
Having a rich, reliable, centralized set of technical documentation might not be the sexiest aspect of your development team, but it can help your team move faster and go from good to great. Here's a quick recap of what we covered:
One of the hardest things to do as a development team is keep everyone in your team and the organization up to date. Some people want to know the status of "Project X", others want to know what new features are coming out and when, and still others want to know what's coming next quarter. Many teams rely on big state of the union meetings or mass emails, but neither option is effective when it comes to transparency or visibility. People miss emails, and emails get buried. After a big announcement, there's no way to reference things said. Plus, there's no simple way to ask questions.
How about a Confluence blog post? In this article, I'll show you how to utilize blog posts to share important news and updates across your development team and greater organization. Blogs are a great tool for keeping teammates and coworkers updated because they don't get buried in all of your email, you can write them using dynamic content like JIRA issues and macros, and they're social which makes it easy to start a conversation with interested stakeholders without a neverending thread of emails. Check out these 3 blogs we publish in Confluence all the time at Atlassian.
At Atlassian, before a new release goes out to customers, a member of our development team writes an internal blog post in Confluence to update Atlassians of what's in the release. Our developers want to know what features shipped and what changes to the products were made. It's the easiest and most effective way to keep everyone up to date.
The easiest way to showcase which features shipped is to bring in issues from JIRA using the JIRA Issue macro , which embeds single JIRA issues or a list of issues in a Confluence page. The embedded issues are dynamic, so anyone can click through to JIRA to get more details about what shipped.
Using the JIRA Issues macro, you can:
It's a powerful macro that brings JIRA into your Confluence pages. Below, you can see how to configure the macro and find the issues you want to bring through from JIRA.
Pro Tip: Display issues using JIRA Query Language (JQL)
You can use the macro to display a table of JIRA issues on your page, based on the results of a search using JIRA Query Language (JQL).
JQL is a simple query language, similar to SQL, which works in JIRA. A basic JQL query consists of a field, followed by an operator (such as = or >), followed by one or more values or functions.
Examples:
project = "TEST"
project = CONF and component = documentation
For more information about JQL syntax, see the JIRA documentation: Advanced Searching.
Many of our release blogs are pretty simple. The JIRA Issues macro is a great way to quickly whip up an update on the latest product release. But often we write release blogs that are plain, old fun too – packed with gifs, funny videos, HipChat emoticons, or rambling banter. Below is an example of a blog post that one of Confluence's technical writer's published to notify Atlassian's about some new features available to doggood on our Confluence instance that we call 'EAC'.
Keeping your blogs fun and light-hearted is a great way to spur engagement with your team or organization. You can see all of the supportive comments inline on the right.
The Atlassian development teams regularly blog to get help with tough technical problems or to share how they've conquered them. One of the best ways to write about code in Confluence is using the Code Block macro.
The Code Block macro allows you to display source code in your page with the appropriate syntax highlighting. You can choose from a variety of different syntaxes and themes to show your code in Confluence.
To add the macro to your page, click the Insert menu in the editor toolbar and select 'Other macros'. This will launch the macro browser where you can search for and select 'Code Block'. Once you do, you can configure the various fields:
Here's an example of a blog post from Atlassian's intranet that highlights how we use the Code Block macro.
Pro Tip: Speed up macro entry with autocomplete
Type { and the beginning of the macro name, to see a list of suggested macros.
It's important to get new hires started on the right foot. At Atlassian, every employee writes an introductory blog post in Confluence. It's the perfect way for new folks to introduce themselves to the entire organization. This is the perfect way to introduce newbies to Confluence and the organization. Atlassians can welcome new hires by adding comments. It's a very positive first interaction with Confluence and the organization at large.
There are a couple key ingredients to a great intro blog post:
You want people to check out your introductory blog post, and the best way to draw them in is with a clever title. Here are a couple examples:
Use page layouts to organize your blog post into sections and columns. A good tip to working with Page Layouts is to click the 'Add Section' button a few times to give yourself some blocks to work with. Then as you build your page you can choose the various column arrangements. You can always switch them later.
The best way to make a great first impression is to wow people with cool pictures of your travels, favorite foods, hobbies, or your family. In Confluence, adding pictures is as easy as drag and drop, so don’t be shy about showing off. Just drag a picture (or pictures) from your hard-drive and drop them into the Confluence editor. Confluence will attach the images to the page and place them inline. You can then click and drag the images wherever you want on the page.
Pro Tip: Give your pictures some style
When editing the page, select the image to show the image properties panel. The panel allows you to change the appearance of an image – set the display size, add a border and effects and link the image to other pages.
By clicking the 'Properties' button, you can give your image an effect, such as the Instant Camera, drop shadow, or curved shadow effect.
When you're all done, you should have a beautiful blog post you can be excited to share with your team. It might look something like this:
Blog posts are a perfect way to make announcements, offer status reports, or share timely information. Take what you've learned in this article to your team and start building a blogging culture that helps unite your development team and your greater organization. Here's a list of what we've covered:
Hope this was helpful! Got an awesome blog post? Tweet a screenshot of it to us @Confluence and you could win some swag!
Loved this page? Share it on Twitter
About this article
By Jamey Austin, published October 7th, 2015.
Documenting your software releases is an integral part of a software development team's job, and it's almost as important as shipping itself. Why?
But here's a guess: this is probably one of your team's least favorite things to do. Well, we've got some good news: it doesn't need to be an annoying chore or a giant time suck.
If you track and report most of your work in JIRA, the integration between Confluence and JIRA makes it easy to insert your release results straight from JIRA into a Confluence page, where you can add more color and detail, publish internally, and also make them publicly available.
Start with the JIRA Reports Blueprint in Confluence. Select Create from template from the top nav (3-dot button next to ) > JIRA report > Change log Create
Select the Change log report to create an internal release report. This report type gives you a detailed summary of the JIRA issues that were completed in a given release or project. Confluence guides you through creating the report and you can clarify which release you want to report on and what to include.
Select the appropriate project. (If you have more than one JIRA instance, also select which site you want to use.) Complete the appropriate fields for the Create a change log screen and select Create. Your change log report will include the data you specified from JIRA, as well as other important page elements that you can edit and fine tune.
You can either create a dynamic or a static list of issues. Because release notes are a point-in-time communication, a static list is best. If you'd rather include a dynamic list, hit the Switch to advanced link and enter custom JQL. (See the documentation for the JIRA report blueprintfor more details.)
Here's what the page looks like in edit mode.
The top of your page:
And after you've saved:
As you can see, this change log is focused on bug fixes.
Confluence will automatically break your release down into "Bug Fixes," "New Features," "Improvements" etc. based on the issue type in JIRA. This automation is really helpful and eliminates the need for lots of manual editing and formatting.
Craft the perfect release notes for your customers again and again by creating your own release notes template. Here's an example of the template we use when publishing JIRA release notes on our documentation site.
Templates
Once you've created a release notes page you like, Confluence lets you "templatize" that page so you can use it again and again. By standardizing your release notes with a page template, you'll establish consistency for everyone using release notes. Learn more about Creating a template in Confluence.
In the template, we've included instructional text to help guide the page creator. The most important thing to include at the top is a small blurb summarizing what's in your release, or the major theme. If it's just a bug fix release, however, there won't be much to add in this space. But if it's a major release, consider adding a blurb about the impact of new features, functionality, etc.
The page includes:
Macros :
Pro tip
Since you'll likely reuse certain content for your release notes, use the Excerpt + Include Page macros to include content across multiple pages instead of adding it over and over again.
Page enhancements :
You can add more detail to your page templates wherever you like. You can organize your internal and public-facing release notes into what was shipped or fixed, with sections for "bug fixes" and "new features and improvements." Add macros, include images, screenshots, and video... the sky's the limit!
Just remember two things:
1. Audience: Who will read your release notes? Think about your audience before you create them.
2. Timing: When will your readers need access to the release notes? Day of release? Before? Use this info to schedule release notes around deployment, to allow time for review, etc.
3. Done: What was completed? Separate your release notes into sections—new features, enhancements, and bug fixes. This makes it easy to see things at a glance.
4. Edit: If you have multiple contributors to your release notes, they might add info you don't want a reader (internal or external) to see. Edit your release notes carefully. Note: sometimes more detail, screenshots, etc. about one feature or enhancement than another will be seen as a reflection of the relative importance or complexity of that item.
5. Facts first: Stick to the facts. Release notes should be on point and concise.
6. Story and message: A storyline can help put your improvements into context. Help readers understand the changes you’ve made and why they're important to them.
Remember, by using a shared document that developers and product managers can update on an ongoing basis, you save yourself from having to do everything at the end. Also, your release notes can seed other communications. Use the content for in-app notifications, product tours, blog posts, newsletter items, or help and support material.
A well designed release notes page template – along with thoughtful, helpful content – will help you create release notes that not only fulfill the duty of documenting your work but something else: good, repeatable, and consistent communications that deepen your relationship with your audience.
Things to add to your release note page templates:
Did you create a nifty release notes page? Tweet a screenshot to @Confluence and win some swag!
Hungry for more?
Download the Software Team’s Guide to Confluence ebook to see all our tips in one place, then watch the blogs in this space to get notified when new tips articles like this are posted. And if that's not enough, sign up for Confluence Insiders - our monthly newsletter covering all things Confluence.
Loved this page? Share it on Twitter
About this article
By Ryan Anderson, published September 2nd, 2015
We make countless tough decisions every day at work that take collaboration and careful deliberation – that's what makes them so difficult. Most teams rely on a meeting to make a big decision, but it can be hard to actually make the decision in person. Many times a follow-up meeting is required. Most people are much more comfortable making a decision asynchronously. There's no place better than Confluence.
We have a saying around Atlassian: Decisions don't require handshakes. The Decisions Blueprint provides a simple, repeatable process for making decisions asynchronously amongst your team and recording them forever in Confluence so you, or anyone on your team, can reference them later.
Let's take a look at 5 steps to setting up a decision page in Confluence.
There are three key components to every decision. What do we need to decide? Who are the stakeholders that need to make this decision? When does it need to be decided by?
Usually this is best answered with another question. What should we name our new Q&A add-on for Confluence? (Answer: Confluence Questions ).
It's best to ask this question in the page title. This makes it a lot easier to find the decision later if you need to search for it.
With any decision, an often overlooked step is defining roles. There are two groups: The owner and the stakeholders. The owner is the person who has final say, this is likely the page author, but could also be the team leader or executive. The stakeholders are the people that need to be involved in making this decision. This is the pool of people that this decision effects.
Use @mentions to share this page with the owner and stakeholders. This will automatically send them an invite to contribute – bringing them into the decision page – once the page is saved. This will save you the time of needing to the share the page after you've completed it.
The thing about decisions is that they have to be made at some point, you can't debate them forever. Set a drop-dead date using the date picker so everyone knows how time sensitive their contributions are.
Pro tip: Skip the 'Background' text field
I recommend that you use the Confluence editor to write down the background of your decision. This will give you the space and tools to offer a complete context filled with links, images, and even video.
Since you're not going to host a meeting – you need to make sure everyone has all the information before contributing their thoughts. In most cases you might have two options A and B. Use Page Layouts to organize your page and separate your options.
A good tip to working with Page Layouts is click the 'Add Section' button a few times to give yourself some blocks to work with. Place your cursor in the second page layout block and click the two column layout.
From here you can begin to set up your two decisions. Add a heading to your first column. A quick way to add a Heading 2 is by typing 'h2.'.
From here, I usually like to organize the options using tables. Tables are powerful tools for organizing information and making your page highly readable.You might want to create a simple pro-con list for Option A. This is simple. Choose a two columns and add 5 or 6 rows. You can always add more later.
Give each of your table column heading. And then using the and emoticon, you can start creating a list. For a check mark, type '(/)' and for a negative mark, type '(-)'.
Pro tip: Add color to your tables
If you want to take your table to the next level, highlight your pro and con list columns.
There may be decisions you need to make where you want to include some images. This is very simple in Confluence. If the image is on your computer, you can use drag-and-drop – bringing the image inline in the Confluence editor and attaching it to the page.
One of the best parts of Confluence is linking. When all of your work and documentation is Confluence, it's easy to link to it and make your teammates aware. This can be really helpful for providing background for a decision. There are a couple ways to link to a page and you can read up here, but in this post, I'll only show you the fastest way which is using autocomplete for links.
Type ' [ ' and you'll see a list of your most recently viewed pages.
As you type, you can search across Confluence for the page you want to link to. It's that simple. If you have the Confluence page link already, you can just paste it directly into the editor and Confluence will automatically convert it to a link of your page title.
You've already shared your page with the stakeholders using @mentions, but if you want, you can share your page again using the Share button. This will send your teammates a notification to visit this page.
Once you have everyone on your decision page it’s easy to foster meaningful discussion. Anyone can comments or like to give feedback, work out details, debate possible solutions, and reach consensus. With all of your conversations in one place, you’ll never have to waste time digging through your inbox to find that email thread again.
You can leave a comment at the end of the page:
Pro tip: Add stakeholders as 'watchers' of the page
Add your stakeholders and owner as watchers of the page. If they miss the @mention notification (or the Share notification), they will see updates as stakeholders begin to discuss the decision.
Or you can leave a comment inline – typically to seek clarification or point something out in the background that you'd like clarification on. To do this, just highlight any text on the page:
Once your team has reached a decision it’s just as easy to record it in Confluence. Change the status of the decision, using the Status Macro, so that everyone that contributed is notified. With everyone on the same page, it’s easy to keep progress moving forward.
Want to refer back to see why a decision was made? The Decision Blueprint automatically indexes your decisions on a single page. Now all your decisions are accessible to anyone who needs them, whenever they need them.
Creating this page might seem daunting with all the macros, but making informed decisions as a group is worth the work. It gives your team one place to discuss your options and save yourself long meetings and even longer email threads. In the long run, you'll be happy that you can make a decision once. Here's a list of what we covered:
This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.
About this article
By Terrence Caldwell, published August 31st, 2015
We've written quite a bit about the conundrum of writing requirements in an agile environment. The most important takeaway is: the best way to kick-off your software projects is to build a shared understanding amongst your team. At Atlassian we find the best way to do this is to create a collaborative product requirement to hash out details for large complex epics. When your requirement doc is created and the details are all in one place, it makes it a lot easier for Development and Design to provide immediate feedback and input. When this happens you can iterate quickly and implement work right away. Here's how you can create that requirement and build a shared understanding in Confluence:
Get started with the special template that we've included. The template will help point you in the right direction, and provide some best practices for what content to include.
Your requirements page might be laser focused on a particular feature, or it might include requirements for a release that includes multiple features. Either way, you should capture key high level details at the top of the page for easy reference.
Pro tip
When you create your first product requirement doc in Confluence you'll notice the project details are in a table located in a page properties panel. The page properties macro is a powerful macro that allows you to create a summary page that pulls in information from multiple pages. In this case, a summary page could bring in each of the fields in your table so you can see who is involved or the status of a given requirements page. Keep reading to see what that summary page looks like
The team goals and business objectives section is meant to give you a chance to add some color and context to your requirement.
A good way to think about your goals is from your customers perspective. What exactly are they trying to achieve? How does the solution you're proposing fit into it?
This is a great place to link to other Confluence pages to provide more detail including customer interviews, and planning pages.
Use a table to list out your user stories, along with description, priority, and notes. This table is another great place to link to more detailed research pages, and customer interviews.
Pro tip
It's really easy to turn the user stories you write in Confluence into JIRA issues. When the page is saved, just highlight the user story text, and Confluence will give you the option to create JIRA issues. If you have a full table full of user stories, you can convert them all into JIRA issues at once.
Drag-and-drop design files to embed them on your page. If you're embedding multiple design assets use the attachments macro to create a quick repository of all the files that are attached to the page.
Pro tip
Confluence is perfect for collaborating on wireframes, mockups, and design prototypes. Use the rich file viewer to prievew PDFs, images, and powerpoint presentations. You can pin comments directly on files to provide feedback in context. Your design, and dev team can spar on early mockups on the same page.
As the team understands the problems to solve, they often have questions. Create a table of "things we need to decide or research" to track these items.
Keep the team focused on the work at hand by clearly calling out what you're not doing. Flag things that are out of scope at the moment, but might be looked at later.
Most likely you and/or your development team spend a lot of time in JIRA. It's really easy to get from your Confluence requirement to your JIRA epic and vice versa. You can view all the JIRA links on any Confluence page, by clicking on the JIRA links button at the top of your saved page.
You're probably not just working on one project. Confluence automatically creates an index page that pulls in the key details of all your team's product requirements. You can always access this index page in the Space sidebar.
t's a handy way to see what your team is or has been working on at a high level. Just like any page in Confluence you can edit this index page as you see fit.
You can edit the Product Requirements blueprint at any time and tailor it to fit your team's specific needs. If you want to edit the template for your specific team or project, go to the Space Tools menu and select Content Tools. Under the Templates option you can view and edit any of the templates included. If you're a site admin you can also edit the global template to customize it company-wide.
The key to agile requirements is buidling a shared understanding amongst your team. The best way to do this is creating your high level requirements doc in Confluence, and collaborating across development and design on crucial issues. Use our template as a guide, and customize it to fit your team or company's workflow.
Here's the completed requirementand a rundown of what we covered:
This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.
Find this page helpful? Share the love on Twitter
About this article
By Jamey Austin, published August 31st, 2015.
We have loads (technical term) of customer interviews documented on our internal Confluence instance, so we thought we'd share our best practices for creating an interview page template. Feel free to make modifications to better suit your process. Remember, Confluence is a canvas to design as you like.
Start off with the essentials. Design your page so you can add company and background information where it's easily accessible. You're providing context for your team, so include details about your relationship with the interviewee, the role of that person, and how the interview came to be. Also, make sure to add what product(s) they use.
The goal is to capture the critical details at the top of your page so anyone can quickly grasp who you interviewed, why, and what you talked about.
A design for your page might look something like this:
The top section of this page is set up to capture the essential interview details we've talked about. It features a detailed title, and company and background sections.
To create a page with a similar design, try this:
This is what it looks like after you save the page:
Note the list of headings created by the macro. The information these heading links are pointing to is described in the next section.
Pro tip
The Table of Contents macro creates a list of headings (in this case, each problem title) that link to a specified section where the full details live. In this example, the headings appear where we inserted the macro in the top "Problems Observed" section and link to the detailed information about each problem in the next section. You can configure your Table of Contents macro to grab headings and create similar lists by selecting edit in the macro and completing the necessary fields. Learn more about the Table of Contents macro.
Note the Table of Contents macro used in the first section grabbed the headings "Design Capabilities" and "Problem 2 - Problem title," which link users here where the full details of each problem are found.
To design the next section of your page like the above:
Pro tip
For each problem, try this method:
Quick tip
Add images to your customer interview pages. Company photos and product screenshots make your customer interview pages better, and adding them in Confluence is drag-and-drop easy. (Or select Insert files and images from the toolbar. Also easy!)
Once you've created a customer interview page you like, Confluence lets you "templatize" that page so you can use it again and again. Learn more about creating a template.
By standardizing your customer interviews with a page template, you'll establish consistency for everyone who conducts customer interviews. The next steps involve organizing, centralizing, and sharing your customer interview information.
Labels make searching for customer interviews simple. At the top of the page where your title ends, select the label icon. Add a label like "customer-interview." Boom! You're done.
After you've added the "customer-interview" label to your page, you can add additional topic labels (product, use case, terminology) at any time. Labels are important in Confluence because they can be pulled into summary lists on an index page via macros. It's a good idea to get in the habit of tagging up your interview pages using labels. This will give you several display options for your index page, like a list of all customer interviews or a list of popular topics.
Another great aspect of Confluence is not only keeping your information organized, but also centralized. Here are some suggested steps for centralizing your customer interviews in Confluence.
It's a good idea to create a customer interviews space and make the home page a customer interviews index page. An index page is great for keeping all your customer interview information in one place.
If your team is small, you may not need a dedicated space for customer interviews. But if you have multiple teams, it makes sense to create a customer interviews space and make the home page your customer interviews index page. Either way, an index page is great for keeping all your customer interview information in one place.
Create your customer interview space
Select Spaces from the header > Create space > Blank space
Important note: this is the home page. Complete the first task by creating an index page (details below), and the index page becomes the home page.
Check out this example from our own Atlassian customer interviews index page, in edit mode:
Pro tip
Two macros are doing the heavy lifting in this example. Let's take a quick look at each:
The final step of your customer interview process is sharing the information. You can do this in two simple ways:
Creating a customer interview page—and an index page to organize and centralize all your customer interviews—will help you to both communicate customer feedback to your team and organization and turn interview information into insights about your products. Remember to experiment with you pages to make them work best for your process.
Here's a list of what we covered:
This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.
Loved this page? Share it on Twitter!
About this article
By John Wetenhall, published August 31, 2015.
Every product release requires a lot of hard work and a ton of coordination between individuals and teams. In some places, a release coordinator takes this on as a full time job, while in others, a developer, product manager, or project manager might be in charge of release planning.
At Atlassian, we use Confluence to collect and organize all the work and information for each release, and to communicate what it's all about to the rest of the business.
I've written before about how we approach releases, what goes into them, and how we organize them. In this post I'll cover exactly how to build an awesome release planning page that will help you do the following:
You can set your release up for success from the start with a single source of truth for everyone working on it. Follow these steps to create an awesome release planning page.
It's essential that anyone who comes to your release planning page can quickly identify who is involved, and what the goals and expected outcomes are. When you're done, the top portion will look something like this:
Start by creating a blank page and then add a two column page layout so you can fit all your key information above the fold. Page layouts are in the editor toolbar here:
Add a table inside it that displays the high level details of your release. We like to use the profile picture macro, which you can find in the macro browser or by pressing { and then typing "profile picture", to display each person's image. This helps people put a face to a name, especially when we're working in remote teams. Hover over someone's name in an @mention and you'll find a bit more information about that person.
Pro tip: Put your table inside a page properties macro so you can create a report with a summary of the key details of all your releases available for easy reference.
You'll also want to capture critical details like the name of the release, expected ship date, and the status of the planning page or even the release itself. We use the status macro to communicate status of pages or individual line items. You'll find it in the "Insert more content" button in the editor toolbar or by pressing {. Change the text and the color to indicate changes in status.
Example planning page statuses: DRAFT IN REVIEW CURRENT
Example release statuses: PLANNING IN PROGRESS AT RISK SHIPPED
We also include the most important goals for the release as well as the non-goals – i.e., things that were discussed that we've actively decided not to include in the scope of the release. It can be helpful to link to decision pages or others with background on how the team established the goals.
We like to sketch a roadmap to get a rough idea of how various streams of work will fit together and to communicate the timing within the team and to others. We use the roadmap macro in Confluence to visualize our plans at a high level. (Note: when we want to create a data driven roadmap and determine what's possible given our resources, we use JIRA Portfolio).
Insert the roadmap macro just like any other macro. You can then create as detailed or as simple a roadmap as you need by adding additional lanes for work streams, bars for epics, and markers for milestones (or whatever combination works for you!). Move the bars around to experiment with different timing, and drag them to resize.
Want to give people a little more context on a particular epic or feature you've listed as a bar? You can link any bar to a page - we often provide a link to a product spec that gives more detail. Click insert to add the roadmap to the page, and remember that if your plans change, your roadmap can, too, just edit it and move things around as necessary.
The final piece in your release planning page is all about connecting people to the information they need. You can do this in whatever way best suits your release process, but there are a few basic tips.
First, link your page to the JIRA epic where you're tracking the work for this release by simply pasting the JIRA link into your table at the top. If this release requires multiple epics, you might want to include them in a table below the fold. Paste the issues in so you get the latest status, dynamically updated.
Second, add the children display macro at the top right of your page, above your roadmap under a heading that says "Related Pages". This displays the child pages (sub pages, if you will) of the release planning page. You can specify how many pages and what content to show in the macro editor.
Encourage your colleagues to create any page that has to do with the release as a child page of the planning page so they're all collected in one spot. You may even want to move other pages to become child pages if they were created before the planning page existed. You can move a page from the "..." dropdown in the top right corner.
Pages that we typically create for a release include the following:
Finally, we like to add links and context below the fold so anyone can get to the additional information they need. Things we typically include:
We finish off the page with a release checklist using tasks. Create a task list with the check box in the editor toolbar, or type a left bracket "[" then a right bracket "]" to create a task. You can assign tasks with an @mention and add a due date by typing "//". This lightweight task list makes sure we don't forget any of the little things before we release.
The end result is a page that covers what you plan to release, why, who is involved, an estimate of the timeline and links to more information for anyone who needs it.
Creating this page might seem daunting with all the macros and information we suggest including, but once you create one, you'll get the hang of it. Here's a list of what we covered, plus links for more detail:
This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.
Find this page helpful? Share the love on Twitter
About this article
By SGD, published August 31st, 2015.
– this really smart guy I work with
I mean it in the most respectful way possible when I say that we software makers are inherently lazy. Else, why would we choose careers making computers do repetitive tasks for us? It's this laziness that also motivates us to continually improve the way we work and the products we make – we want life to be easier for both ourselves and our customers.
But learning and improving is really hard if you have to learn the same things over and over again. Even the ancient humans knew this, so they got into the habit of writing stuff down (proving that software makers don't hold a monopoly on strategic laziness). Fortunately for homo modernus, we can skip the carving of stone tablets and use Confluence instead.
As software makers, we rely heavily on sprint retrospectives and demos to learn more about what's going on with our team and our products. Read on to see how to build pages that record what you've learned and let you share it outside your team.
Confluence gives you a big leg up with the Retrospective Blueprint. If you've never used a blueprint before hit the ellipsis next to the Create button at the top of the screen, select Retrospective, then hit the Next button. You'll be prompted to choose a title for the page and indicate which team members participated – they'll be @mentioned on the page, which means Confluence will share the page with them automatically.
Once that's all set, click the Create button at the bottom of the dialog to fire up your new page. You'll notice that the blueprint divides the page into sections with different layouts – full-width for the top and bottom sections, and a two-column layout for the middle one.
Although the blueprint doesn't call for it, I like to add a sentence or two describing what our focus was for this sprint to help jog our memories when we come back and look at the page a month (or year) later.
The Retrospective Blueprint defaults to a "what went well / what didn't go well" format, which allows the whole team to help translate one person's feedback into actionable tasks. If your team is more experienced, you can easily adapt the blueprint to use a "start / stop / continue" format – either instead of or in addition to the default sections provided.
To split that section of the page into three columns, place your cursor in one of the two existing columns, click the Page layout button in the editor, and select the three-column option. Then copy the contents of an existing column into your new third column and update all three headers appropriately. And if you use both mechanisms in your retrospective, add a new section to the page by clicking the Page layout button, then Add section, and choose the three-column layout for the new section.
Now you've got an easy way to capture and categorize the things you and your team discuss. But how do you know which are the most important points – the ones you want to make a priority in your next sprint?
At Atlassian, our teams put it to a vote. Each team member gets to up-vote 3 items in each category, which we represent with an emoticon placed next to the item. Here are some suggestions:
– keystroke is :-P
Pro tip
You can change the background color of a Panel macro by clicking the panel and selecting Edit. I like a nice, calming, everything's-cool blue background when adding a "keep doing" section. Try #334C80 for Border Colour and #F0F5FF for Background Colour. All you need is the hexidecimal color codes to customize the look of your panels.
Once you save the page, those panels will look something like this:
Another habit of highly-successful teams is for team members to acknowledge each other for the good deeds they did this sprint. (Note: managers are barred from giving or receiving acknowledgements – this is meant to be strictly peer-to-peer.) Above the "Actions" section created by the blueprint, type "Acknowledgements" and format it as a section heading by clicking on the Paragraph menu, and selecting Heading 2. Underneath, transcribe the kudos your team gives each other in a bulleted list.
Finally, don't let your great ideas go to waste – take action. The blueprint adds a section for this automatically and gets you started with an empty checklist. Three formatting features come in really handy here:
You probably looked at this headline and thought "Huh?!" No worries – we tend to think of demos as happening live and in the flesh (or at least in real time). But for distributed teams, that's not always possible. (And let's face it: distributed teams are as ubiquitous in the software world as Elvis is in Las Vegas.) So when you can't get everyone online at the same tie, recording demos using screen capture tools like Camstudio or Jing and embedding the videos on a Confluence page is a great substitute for doing it live.
Start by creating a good old fashioned blank page and give it a sensible title that'll make it easy for team members to find through Confluence's quick search or by browsing your team's space. For example, you might create a parent page called Retrospectives, then child pages underneath for each sprint's retrospective notes.
Bonus points if your parent page uses the Children display macro (which does not actually crawl Facebook and display pictures of your children on the page – because that would be creepy). Anyway...
Wherever you choose to create the page, you now get to use your new friend, the Page layout button, to add sections for each office or locale. I like to use a full-width (single-column) section for the headings, and insert a grey line that extends all the way across. To add it, go to the Insert more content menu and select Horizontal rule.
For the sections containing the demos themselves, use a two-column layout to keep the page's content compactly organized and easy to read. In the left-hand columns, insert a table to hold information about who is presenting and the theme of their demo. Below that, embed the relevant JIRA issues using the JIRA macro, or simply by pasting in the link to each issue, as I mentioned above.
Pro tip
This Profile picture macro is perfect for placing in each section. It's just nice to be reminded of what your team mates look like when you don't see them every day
Over in the right-hand columns, ask each team member to embed their screen captures using either the Widget connector or Multimedia macro. Both are available from the Insert more content menu – choose Other macros at the bottom of the menu to bring up the macro search and selector screen.
Pro tip
If you're freaked out by the idea of putting videos of your un-released work out on the internet where users and competitors could discover it, you're not alone. Try creating an account for your team on Vimeo – it's a lot like YouTube, but they make it super easy to add password protection to your videos.
Once you've save the page, it'll look something like this:
We've covered a lot of ground here: blueprints, and page layouts, and macros (oh my!). Here's the highlight reel.
This post is part of our latest collection, A Software Team’s Guide to Confluence. Click the lovely green button below to see more.
Loved this page? Share it on Twitter!