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!

nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

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!

Accepted answers

Matt Reiner (K15t)

@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.

All comments

CARLISLE_9wxp32

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.

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

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?

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:

The team plans the product development work by creating issues.
You create a sub-task under each issue that needs to be documented. (this could be automated with Issue Templates for Jira)
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.
When you work on the documentation, you move that subtask along the board to communicate progress.
When review is needed, assign the subtask to reviewers, and then assign it back to yourself for revisions.
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!

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.

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.

Matt Reiner (K15t)

@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. 🙂)

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.

CARLISLE_9wxp32

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_9wxp32

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.

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

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

confluence

task

documentation