Can I use Confluence for creating tech docs AND for tracking tasks related to those docs?

[Eileen Palsson]

The title says it all. I'm evaluating the possibility to move our documentation from Word to Confluence.

However, first I need to get a grip on all the documentation we have and what tasks are in progress. That is the priority. Below is an idea of the way I think we need to set it up. As you can see, somehow we must be able to link each task to multiple documents, without creating another instance of the task. AND each document is published in multiple languages, so I have to be able to see, for each task, which languages are done.

So many details! Is there going to be a way to do this? Any suggestions/advice? 

And will it be possible to later migrate the actual documents over to Confluence? (This is less important right now, but I'm wondering.)

Space: Technical documentation

Page: Specific document

• Document name
• Description and comments
• Owner (Confluence user)
• Category – for example quick guide, installation guide, user guide, etc.
• Language – Swedish, Norwegian, English, ...
  With last publishing date of each language.
• Importance of this doc in our collection (maybe low to high or a numerical value)
• Whether a QR code is used on packaging to open this doc (yes/no)

Sub-pages?: Tasks

• Task name
• Description and comments
• Priority – critical, important, medium, low
• Status -- Not started, started, finished, published, postponed/waiting
• Assignee (1 user)
• Which documents (pages, I assume) does this task need to be done in?
  We do not want to have to create a task for each page.
  • Create sub-sub-pages for each language of each doc that the change has to be made in?

Many thanks in advance!

[Matt Reiner _K15t_ · Accepted solution]

@Eileen Palsson Here's a suggestion that might work for you:

Create a Jira project for Documentation improvements; let's call it DOCIMPRV.

Anyone can create an issue in DOCIMPRV when they see documentation that needs to be updated. Within the issue, they can link to any Confluence pages that need to be updated. Here's an example:

You can create these types of improvement tasks in Jira and view them using filters, or by viewing the backlog for the DOCIMPRV project. This gives your your list of things to improve.

Now, in Confluence, when you're updating any page, you and your team can look at the list of Jira links to see which issues have been resolved, and which need to be worked on.

(imagine the list being longer. 🙂)

When someone updates a page, they can add a comment to the issue saying they've made the update on that page and then have them remove the link to the page so the issue no longer shows up on that page and vice versa.

This way, when you're looking at the issue, you'll only see pages that still need to be updated and when you're on a page you'll only see issues for tasks that still need to be completed on the page.

[Matt Reiner _K15t_]

I wanted to add this here. It's a guide for technical docs in Confluence: https://www.k15t.com/rock-the-docs

[Jason Rogers]

Hi Eileen, 

Confluence is a great tool for storing user guides, technical documentation, process diagrams etc.. I use it alot for this purpose in my company. There are alot of helpful macros that you can use too. You can create links to various pages, content tables, list contributors, display status', version control etc.. You can also use the Office Word macro to display an existing word doc. by attaching it to the page. It will then render the document onto Confluence - but as Carlisle above mentioned, the formatting may be an issue. Also I would not encourage adding lots of attachments to a Confluence page as it will affect perfromance. All in all, Confluence is good for documentation.

However, the best tool for tracking issues/tasks related to these documents would be Jira. If you have Jira you could then set up a project to associate with a document and use the issue filter macro, or the JQL report macro to display all associated issues/tasks with the documentation, in Confluence. This will display multiple issues/tasks on one page, instead of having to create a sub page in Confluence for each task. 

Hope this helps

J

[Eileen Palsson]

Thank you, Jason. I appreciate your input!

Our company's Jira & Confluence guru believes that Jira is the wrong tool for tracking issues/tasks, because:

• Each "project" or "story" in Jira would be never-ending. With our documentation, we don't work on projects where each release has to include X, Y, and Z. Rather, each document can be improved/updated at any time.
• Each issue/task has to be included in multiple "projects" or "stories". There doesn't seem to be any way to do this without copying or cloning each issue for each project/story. And if we had to do that, we'd be almost right back where we started.

He's still willing to set it up for us for testing, so any additional comments or suggestions are very much appreciated. Are you suggesting something like the following?

• Each document and each language version is a space? page? in Confluence.
• Each task is entered in Jira ONCE (as a project??) and linked to each space/page that it needs to be done in.
• When the task has been completed in each required place, that task/project is done/resolved.

Really grateful for suggestions. (Even a suggestion that we use another tool.) Thanks again.

[Matt Reiner _K15t_]

Hi @Eileen Palsson, what a great question.

I moved from DITA to Confluence in my last gig, and the change was profoundly positive. You've got the right idea for sure. :)

So to answer your questions, I have a few different thoughts:

Task Management

To first address task management, I think Jira might be the tool of choice. There are many different ways to use Jira to manage documentation work, so I'll make a guess based on how I think your team might operate today:

There is one or more team that works on your different products, each within their own Jira project. As you mentioned, you will most likely not want to use a separate documentation project, rather, create documentation issues within the project of the product you are documenting. This is helpful in a few ways:

• You can directly link product development issues with documentation issues so the team can easily reference each.
• Bring greater visibility to documentation work by connecting it to product development Jira issues and even including documentation issues on the project board.
• Streamline subject matter expert review by assigning them review work within the same Jira project they work in every day.
• Create a board that shows documentation issues from all projects so you have one place to look at all the documentation work to be done.

Here's one way your process could look:

1. The team plans the product development work by creating issues.
2. You create a sub-task under each issue that needs to be documented. (this could be automated with Issue Templates for Jira)
3. Link one or more documentation pages that need to be updated to the issue. If a new page must be created, note that in the description in the Jira issue and link it once it's been created.
4. When you work on the documentation, you move that subtask along the board to communicate progress.
5. When review is needed, assign the subtask to reviewers, and then assign it back to yourself for revisions.
6. When the documentation is ready, move the subtask to done/resolved.

There are lots of different options when it comes to creating, organizing, and distributing your content.

Content Information

• Document name—Page name
• Description and comments—Excerpt macro on each page, and Confluence comment area and inline comments.
• Owner (Confluence user)—Jira issue assignee and also people can watch pages to be notified if anything changes
• Category—This is a great use for page labels in Confluence. You can also create page templates to give writers a head start on how each type of page should look.
• Language – The best solution here is an app my team makes, Scroll Translations. You can manage multiple translations on each page, so it keeps things simple.
• Last publishing date of each language—You could display this on the web through your theme or when you export the documentation as a file, like a PDF or Word file.
• Importance of this doc in our collection—Would be another use for page labels.
• Whether a QR code is used on packaging to open this doc—You could use a Page Properties macro for this, which can be included in your internal reports and such, but hidden when users read the page.

Managing Changes

You may need to keep track of different versions ad variants of your documentation so you can distribute each to your users. Scroll Versions is the app for that. :)

Distribution

When you go to distribute your content, there are few different options:

• Confluence Word and PDF export—Hard to customize, but they get the job done
• Scroll Exporters—Visual template editor and full control over what content is exported.
• Allow anonymous access to the documentation space(s) so the documentation is publicly accessible online.
• Theme the space with tools like Scroll Viewport or Refined Wiki

Word Import

I know you're not thinking about this right now, importing your content from Word would reduce a lot of headache for sure. :) @Jason Rogers' idea of using the Office Word macro to display the Word docs into Confluence is a great start, and when you're ready to move the content right into Confluence, let me know. My team has done these sorts of imports before, so we can help with that transition.

I've made a lot of assumptions here, so let me know if I'm off base or if you have other questions.

[Eileen Palsson]

Hello @Matt Reiner _K15t_ and thank you for your detailed suggestions.

Everything you described under Task Management is in line with what I now realize is the way things should be done. At my previous job, we used almost exactly what you described, but using a different tool.

So yes, absolutely, we will be doing that. Thank you.

However, we still need some type of master list of the many documents & translations that we are responsible for, with a bunch of properties for each.

Above all, we need a collection of tasks that can be filtered by what docs the tasks apply to. 

Why a task collection, if we have our tasks in Jira? Because there are countless tasks that aren't related to a development project. (It could be a mistranslation or formatting problem that needs to be fixed, or an example that Support has requested we add to document(s), or mention of an obsolete product that can now be deleted.) 

So, when I edit a document based on a task from Jira, I want to be able to easily find all the non-project-related tasks related to that doc, and take care of those issues at the same time, and register that those tasks have been done in that doc.

I think we should do this in Confluence. But how to set it up? Something like in my original post??

Our current system (you can skip this):

A big Excel spreadsheet lists all the docs and all their properties. Each row is linked to what is basically a Word to-do list. Each to-do list is in turn linked to the document itself. 

A big problem is that if something has to be done in 4 different documents, then the task description has to be manually copied to 4 different to-do lists. And if somebody changes a detail of the request, then that change has to be made in all 4 to-do lists. Which means that each to-do list has to mention all the other to-do lists that the task is included in. And if (heaven forbid) someone realizes that this change should be done in yet another document, then we have to not only add it to the 5th to-do list but go back and mention that 5th to-do list to the other 4. :-/ 

Completely unmanageable. 

Thank you again!

[Matt Reiner _K15t_]

@Eileen Palsson, ah, I see what you mean. This makes sense. So here's a suggestion that might work for you:

Create a Jira project for Documentation improvements; let's call it DOCIMPRV.

Anyone can create an issue in DOCIMPRV when they see documentation that needs to be updated. Within the issue, they can link to any Confluence pages that need to be updated. Here's an example:

You can create these types of improvement tasks in Jira and view them using filters, or by viewing the backlog for the DOCIMPRV project. This gives your your list of things to improve.

Now, in Confluence, when you're updating any page, you and your team can look at the list of Jira links to see which issues have been resolved, and which need to be worked on.

(imagine the list being longer. 🙂)

When someone updates a page, they can add a comment to the issue saying they've made the update on that page and then have them remove the link to the page so the issue no longer shows up on that page and vice versa.

This way, when you're looking at the issue, you'll only see pages that still need to be updated and when you're on a page you'll only see issues for tasks that still need to be completed on the page.

I hope this makes sense. If not, maybe we should just jump on a video call. It'd be much easier to show on video.

[Eileen Palsson]

Awesome -- this makes complete sense! Thank you for the detailed explanation and images!

(I wish this were on the main level so I could click "Accept answer".) 

One last question: As I mentioned, we do not yet have our documentation in Confluence. It will be awhile. Is there perhaps a way to implement this scenario beforehand?

Our documentation is on a server, and we can link to those files, so maybe create a Confluence space (page?) to represent each document? Hopefully in a way that would pave the way for migrating the docs to Confluence?

Thanks again -- your detailed example was supremely helpful.

[Matt Reiner _K15t_]

@Eileen Palsson, happy to share. Maybe I'll post this again so you can mark it as an answer. (I love it when I can quickly find an answer to a question like this 🙌🏻)

I think creating pages for each document is a good first step. I'd recommend you create the spaces you think you'll end up with, and then pages for the documents.

Also, maybe use @Jason Rogers' idea of using the Office Word macro to display the Word documents on these pages. That way people get used to going to Confluence to read the documentation, even if the content doesn't actually live in Confluence yet.

[Bill Bailey]

Well I would strongly recommend against any scenario that lets users be in Confluence but still use Word. You will never get them to switch, and they will insist in staying in the Word domain (for example, aks you to export Confluence content to Word so they "can work on it").

I still have problems today, 2 years in with users always starting docs in Word because it is "easier", then sending it to me later to import into Confluence,to start the review process. It causes more work and makes the authoring process slower as they are emailing drafts.

I would start any new docs in Confluence now (cold turkey). And any docs that are in WiP, import them (the function works reasonable well with clean up). The sooner you can get the user base working in the Confluence domain, the sooner you will reap the benefits.

Suggested Structure

From a structure standpoint, we created separate spaces for each doc type, for example, user guides, application notes, white papers, etc. Besides an organizational benefit, it does help lower the risk of name space collision when users create new pages.

Real-Word Example

I did a lot of contract work for another client who had a user guide that had been done in Frame (which I love), but had never completed reviews. We would make changes and send out long PDFs to get reviews and corrects. Getting reviews done was really slow as users felt they were required to read the entire doc each time. This process was ongoing when I picked up the doc, A year and half later, there were still issues that went unaddressed.

I helped move them to the Confluence domain where we authored the same type of guide for a new product. We got the guide out in 6 months. The ability to have multiple people working/review a doc at the same time really helps, plus it was far easier to focus users to address a specific issue on a single page quickly. And this was before inline commenting!

So run, don't walk towards Confluence and away from Word.

[Eileen Palsson]

@Bill Bailey, about this part of your real-world example:

The ability to have multiple people working/review a doc at the same time really helps, plus it was far easier to focus users to address a specific issue on a single page quickly. And this was before inline commenting!

If it's not too much trouble, could you point briefly take me through the review process you implemented in Confluence? I'm especially interested in how people were notified that there was something for them to check or collaborate on. 

Does each reviewer/collaborator require their own Confluence license? Or can there be a floating license that reviewers can log in with? 

Thank you!

[Bill Bailey]

Well there are two approaches, but note first, every reviewer needs an account for your Confluence instance - basically one license for everyone in the company.

Informal Approach

Rather than emailing individual files, pages can be shared with individual users. stating what needs to be done.

Also, anyone who edits a page, gets email notifications when edits are made to a page. An admin can also assign watchers to a page. In this case, you could designate champions for each page and they are responsible for monitoring the page.

More Formal Approach

Use the builtin task system to assign doc review tasks (see add-assign-and-view-tasks). User are emailed, and can source a management dashboard through reporting.

Formal Approach

Develop a workflow using a commercial plugin (comala-workflows) to create a formal workflow to move a page through a defined workflow with task assignments, email notifications, etc. This last approach takes time to implement, but it does make it clear where each page it, and who needs to do what. And there is support for top-level reporting.

[Matt Reiner _K15t_]

On my last team, we used Jira to manage our doc process, since the rest of the team was using it for dev tasks. This was a good way to increase visibility for the team, but it didn't give the same kind of great Confluence visibility like with Comala.

[CARLISLE]

First off Welcome!

You can think of the Confluence tool as a modern printing press that is able to handle the volume of publishing in house. The Document Name, Description, Owner, Category, and such should all be available. Please keep in mind there are various customizations available and Add-Ons as needed. The Atlassian company is global and can handle various languages. The sub-page functionality more than likely can be found using JIRA another tool. I have not seen a QR integration for any customer as of yet, but it appears to be a new tool in the TECH world these days.

As far as parsing data from Word into Confluence, this move quite possibly might be a bit difficult. One customer has attempted to do this move and formatting issues on the parsing has been a bit heavy.

[Eileen Palsson]

Thank you! And thank you for your comments. 

I realize now that my title was actually a bit misleading. My main focus at the moment is getting a grip on the tasks associated with documentation.

Most of the tasks have to be done in multiple documents and/or in multiple languages. I need to be able to get a list of all the changes that need to be made in the Finnish version of the XYZ installation guide, for example -- without having to recreate the same task for each place where it needs to be done. 

Any ideas?

[CARLISLE]

The tasks management tools will not be in Confluence, but more in JIRA from a project management perspective. Confluence, keep in mind, is kind of a content management system. It depends on the task at hand and if you are delivering a AGILE style of system. JIRA manages an AGILE form of delivering software and such. All tasks and sub-tasks are managed through JIRA. 

Take your time to read the technical specifications directly from Atlassian as it will have all the necessary details about a proper infrastructure deployment for your team.

[CARLISLE]

OH! And keep in mind tasks can be shared across different sprints in your Project or Board. Therefore, as you asked, you will not have to recreate a task as that same task can be shared across various Projects or Boards. Consider it a global programming change that will be spread across the entire team task list.

[CARLISLE]

Keep in mind that consultants are just selling and the people who built this tool/use it daily and know how it works.

The translation services will be a bit difficult. Google is leading the way in translation services for programming with WordPress for publishing. I will test with my in house team to see how translations actually function on site with real customers doing the work. We are working in the USA with Spanish translations. As far as Finnish or other languages, then I will have to check with our European team on that one. We have Edward, Max, and Thomas looking into that one.

[Bill Bailey]

@Eileen Palsson, I am on my second company using Confluence for all technical documentation. Confluence is an excellent platform for content development and delivery. Of course, there are many ways to construct your solution, depending upon how you plan to delivery your documentation to customer: via Confluence or PDF.

Cadillac System for Delivery of Confluence-Based Docs

With the first company, I created a dual-server solution: the internal for doc development, and a customer-facing server for delivery to the customer. This arrangement insured that only publish docs were stored on the external server, and created an air-gap between internal info and the public.

Then I developed a workflow using Comala workflows. which covered the doc process from womb to tomb, tracking the status, assign author, and review tasks automatically, and in the end pushing the final version out to the external server. This made if very clear at what state each Confluence page was in and who was responsible.

Then using a reporting plug in, rolled up the status of each doc to a management dashboard. It made it very clear to review where docs where at, and who was holding it up.

I also created a short-loop flow to be able to fix typos and republish quickly.

In the end we had a very automated system that reduced my management load -- I was supporting 50 engineers.

With this structure, each Confluence page is independent of the other, and updates can be pushed out as soon as they are ready. Customer are always viewing the current version.

Chevy Solution for Delivering Docs as PDFs

My current company opted for this solution, where we have a single Confluence server, and deliver documents as PDFs. Key to this solution is the Scroll PDF Exporter (version 3.5.1 as the new version stripped all of the power-user features out). With work on the templates, export schemes and user macros, we can generate PDF output that looks decent and acceptibale (hard to get to what you would get with FrameMaker).

Judging from your requirements, you coudl go with a trackling solution based on the the Page Properties Macro and the associated reporting macro, using user macro wrappers on the Status macro (see my article here). Then create a page template to hold the base table with your custom macros for creating the blank pages.

Each time a new page is needed, use the template to create the skeleton, set the various macros. As the page is edited, the status macros can be updated.

Then you have create a dashboard that reads these valuse from each page --voilá you have a status tracker!

As you can see, there are many ways you can structure a doc solution with Confluence.

P.S. My opinion of Word as it useful only for writing letters to Grandmother. ;-)

[Matt Reiner _K15t_]

@Bill Bailey Love the use of "Cadillac" and "Chevy" here as well as the great use for Word.

Well said. 😂

[Eileen Palsson]

Thank you, @Bill Bailey! I will definitely come back to this when we are ready to move the documentation itself to Confluence.

[Luc Filion]

@Eileen Palsson Hello Eileen, This plugin might help : there's plugin that actually lets you create Templates of both Jira+Confluence items (documents and tasks in your case). This will automate task and document creation, and let you track the progression of them through a dashboard. See Gaia Activity for Jira.