If your organisation has a range of similar products, it’s likely that the documentation will have some common content. For example, you may have several products that all need the same safety warnings or legal information. As a writer, you need an easy way of managing and updating this common content, and that’s exactly what Flare’s Global Project Linking feature is for.
In this post, I’m going to briefly look at what Global Project Linking is and the benefits it offers. Then I’ll share some tips on how to organise a global project so that writers can use it effectively.
- What is Global Project Linking?
- Benefits of Global Project Linking
- Structure your Global Project for Productivity
- Keep your Global Project Tidy
What is Global Project Linking?
With Global Project Linking, you use a ‘global’ project as a library of common content, which can include topics, snippets, stylesheets, and more. You then set your documentation projects to import content from the ‘global’ project.
Benefits of Global Project Linking
Global Project Linking reduces the amount of effort required to update your documentation, and also helps to maintain consistency. As the common content exists in one place (the global project), if you need to make changes, you can make them once and then import them into your projects. This is much quicker than applying the changes separately to each project, and it also ensures that the content is consistent.
To make importing even easier, you can set your projects to auto-import from the global project at build time. That way, your project always uses the most up-to-date version of the common content. To learn more, view the Flare online Help topic on setting up global project linking and auto-imports.
Structure Your Global Project for Productivity
While there are clear benefits to using Global Project Linking, this type of setup also presents you with a new challenge - how are you going to organise your reusable content?
I’ve faced this issue on several projects, and here I’m going to share some ideas on how to plan your structure. While they won’t suit every project, they should be a good starting point and will give you an idea of the sorts of things you need to consider.
- Analyse the Needs of Your Writers
- Identify What Content is Going to be Reused
- Organise the Reusable Content
- Keep Your Global Project Tidy
Analyse the Needs of Your Writers
Organising a global project is very similar to planning a technical document - you need to look at it from the audience’s perspective. In this case, the audience is your writers.
- Who are your writers? I recommend that you consider the position of a writer who is completely new to your project. You never know when you might need to add a new writer to your team or hand the project over (lottery wins can happen!).
- What do the writers need? To be able to find each type of reusable content easily and quickly, without requiring in-depth knowledge of all of your projects.
If your writers are going to use a global project efficiently, it is vital that you consider their perspective. If a writer can’t find the information they’re looking for, they will probably create it from scratch. That leads to duplicate content, which defeats the point of a global project. Of course, it also means that you have writers doing work that has already been done.
Identify What Content is Going to be Reused
It is easier to identify the types of content you are going to reuse if you have a good understanding of your content. But sometimes that isn’t easy to achieve. For example, on at least one of my projects, new manuals were being added regularly, and I had no idea what they were going to contain. But the basic structure that I had set up in the global project accommodated them quite easily, and it has worked on other projects as well.
In my basic structure, the following content types are identified:
- Concepts (introductions, explanations, etc.)
- Process steps
- Examples
- References, such as telephone numbers and addresses
- Tables
- Images
- Videos
Of these, I put concepts, process steps, examples, and references in snippets. You might find that a similar approach is a good starting point for your content reuse.
Note: I use snippets for references instead of variables. This is because you can format the content in snippets, but you can’t format the content in variables.
Putting individual steps of a procedure into snippets can seem like reuse overkill, but it has been a real time-saver on lots of my projects. It makes it easier to update the steps, as they exist in one place. They are especially useful on software projects, where last-minute name changes are common.
If you are going to put process steps in snippets, I recommend that you strip them down to the minimum amount of information required, so that they make sense when reused in different contexts. For example, let’s say you have two steps:
- ‘Click Edit and then select Format’
- ‘Click Edit and then click Layout’
For reuse, it would be better to have these as three steps:
- Click Edit
- Click Format
- Click Layout
Each step is then more reusable and if the name of an option changes, you can make one update instead of two.
Organise the Reusable Content
At first, you may be tempted to organise your Global project with a folder for each project and a folder for ‘common’ content. It makes sense in terms of what the global project represents, but it means that a writer needs to have knowledge of what is in each project. Without that knowledge, how can they:
- Determine which folder contains the snippets they want to use?
- Know whether a snippet is only reused in one manual?
- Know whether a snippet is reused in several manuals and so is a ‘common’ snippet?
- Know that content in a new project already exists in one of the other projects?
A better approach is to organise the content based on the type and meaning of the content. The important thing here is to make sure the sub-folders are meaningful and don’t require the writer to already know the content. If they are looking for reusable steps, they start with the Process Steps folder, and then look for the step(s) that they want. They don’t need any prior knowledge of what is in each of the projects.
The images above show two different approaches – on the left, the content is organised by type and then subject; on the right, it is organised by subject and then type.
Organising your global project in this way also helps to future-proof your project. If you have to add a new project, it is likely that its content will fit into this structure. If it doesn’t fit this structure, you can add folders to allow for the differences, again based on type and meaning.
Tip: If you find that there are too many levels of information, try to remove one of the upper levels of folders. The lower levels are usually closely related to the meaning of the content, which is the most important part.
Tip: Another thing to consider with global projects is conditional text. To avoid confusion between writers (and possibly translators too), keep your conditions simple. The more complex they are, the more confusing they can be. I try to limit conditions to just the different output types and projects (or product versions). On a couple of projects, I’ve seen writers use dozens of variations, and it leads to misunderstandings.
Keep Your Global Project Tidy
Once you have organised your global project, it is a good idea to plan for regular maintenance on the folders. Even when there is an agreed policy in place, you may find that writers place snippets in the wrong folders or include other files that should not be there. This is just one of those things that happens, especially when people are rushing to meet deadlines. So allow some time to keep things in order.
Tip: When you import from the global project into a regular project, an import file is created. Over time, these may affect performance, so consider clearing out the import files in your projects on a regular basis.
Conclusion
I’ve used this approach to global projects many times, and it has helped to speed up the production of content, especially when there are multiple writers. It has also helped people who are new to the idea of content reuse understand the benefits of writing content in one place. I hope it proves useful to you too.
