How to organize projects for white-labelled documentation?

[tbschaus]

I'm looking for suggested best practices.

I curate four full libraries of documents, each of which has different branding i.e. three of them are white-labelled channel partners.

Much of the content (i.e. the topics) is the same; however, each library of documents is styled according to very different brand guides.

Here's my question: as we migrate from Word/PDFs to online/mobile/PDFs using Flare, should all of this documentation fall under the same project? Or is better to create a separate project for the documentation of each channel partner?

If we create separate projects, can we share topics between them?

Thanks, in advance, for any help

[Msquared]

I'll answer half your question (all channel partners in one project). I'm still working out the best answer to the other half myself (all documents in the set in one project).

Definitely, definitely put the documentation for all the channel partners in the same project. That's exactly what I do, and exactly what Flare is good at. To keep it simple for explanation, let's consider a single document that has a PDF output, produced for each of your four brandings (I have three different brandings).

I have the following:

Variables for things that are different across brandings (in my case, for example, the product name, release date, software version etc)

Conditions for each branding, to allow me to control minor content differences (in my case, brand A, brand B, brand C, so I have A Only, B Only, C Only)

Different page layouts for each branding, again in my case, one for A, B and C.

Some different topics, for example the Title page and Preface section for B and C are specific to the requirements of our partners.

Different styles for each branding. You can put them all in one style sheet and use different media, or have separate stylesheets, which is my personal preference. For example, my heading 1 style for A is coloured, and black for B and C. Fonts, spacing, table styles etc are different too.

Now it gets clever . . .

A single TOC for the document, that contains all the topics for all the brandings. For example, it has all the title pages, all the prefaces, all the topics. Where a topic or part of a topic is not relevant to all brandings, it has a conditional tag. For example, topic X only applies to A and topic Y applies to A and B. So X has condition A Only applied, and Y has condition A Only, and also condition B Only.

A target for each brand of the document. In this target, set the appropriate condition, variables, stylesheet and media, page layout etc. So my target A has conditions A Only set to Include, and B Only and C Only set to Exclude (include overrides exclude). The values for the variables are set to the appropriate product name, release date, software version etc.

I've kept the description simple, but I also single source three WebHelp targets from the same TOC. This may not work for everyone, but if your WebHelp is based on the same content as your PDF, which, rightly or wrongly, mine is, It's easy to do. I have Print Only and Web Only conditions, different skins for each branding, more stylesheets for each web style etc.

Your second question. Should you put all your documents in one project? There are others here who can advise on that better than me, and the best answer for you will depend on the number of documents, writers etc. Flare certainly allows you to share topics and import topics between projects and to keep them in step (search the help for Global Project Linking). But you can also build multiple documents from the same project and people tell me Flare can cope with a single project with thousands of topics.

I originally planned a Global project, for genuinely global things, like stylesheets, page layouts, logos, web skins etc, a Shared project for content that is common to more than one output, for example, concept information that is required in more than one document. But in fact, most of my documents are currently in one project, in separate sub folders. I just have a separate TOC for each document, and a separate target for each branding of that document. The topics for that document are just in a subfolder of my Content folder. But as I port more content to Flare, as the day job and the release schedule allows, I think I may go back to plan A. I'm a sole author, so it's only me that is affected by my indecision.

If you do decide to use a single project, I'd advise you to make sure you have a clear structure and naming convention from the outset, as it's easy to get confused once you start serious single sourcing. For example, all my global content is prefixed with GLOBAL.

Keep posting the questions. Several very experienced and helpful MadCap users hang out here. I've learned lots from them.

[tbschaus]

Thank you, Msquared, for your thorough answer

We're trying to anticipate as much as we can in the planning stages, and you've helped with that... a lot.

Brent

[Msquared]

Glad to be of help.

Before I started with Flare, I spent quite a while working out what the various moving parts were, and how to single source PDF and WebHelp content for three similar but subtly different products, each with different brandings. It took me a while to get my head round it all, so I've been there.

A few other things you may find helpful to know before you start porting your Word content.

It is worth spending some time structuring your Word content before you start importing it for real. You may be lucky and have well-structured content already - I didn't in the main, but the time I spent reorganising my content was well worth it. Once you chop your content up into topics, if they are the right topics, they are easier to manage than a monolithic Word document, but if they're not the right topics, it will be harder initially.

It is also worth cleaning up the formatting of the Word content, as it will import much more cleanly if all your formatting uses Word styles, rather than local formatting. There I was lucky. I'd recently redone all our Word templates and applied the styles consistently. So I was able to take my Word content, do a trial import into Flare and select the option to keep the Word styles. That generated me a Flare stylesheet with CSS for all my Word styles. I didn't use that as my final stylesheet, but as I wasn't very familiar with CSS at that point, it gave me an basis for my own stylesheet. I did this for each of my different brandings.

You will want to impose some structure below your Contents folder in your Flare project. I currently organise mine by document then by chapter, but I know others do different things (my structure does rather miss the point of topic-based authoring, but it works for me for now). What's important to mention at this point is to watch the file name length of the higher level folders. Windows has a limit (248 characters for folder names, and 261 for file+folder names, I think, strange as these numbers seem). You can reach this surprisingly quickly in a Flare project structure, since your topic file names will probably be reasonably long, or you won't be able to tell them apart when you have hundreds of them. You may have some workspace structure imposed by your source control system, then perhaps some project structure, especially if your documentation sits within a larger code base, then the structure of your documentation folders, perhaps a layer for different language translations, then your Flare projects, then within the Flare project, the Contents area, and below that, your contents structure. Flare builds its outputs below \Output, in folders named after your target names. Your target names are likely to be reasonably long, as you'll probably want to encapsulate the document, channel branding and output type in the name. Below this, for web outputs, you'll get your Contents folder, and your contents folder structure below that. By now, your thirty-character topic name may be too long for your WebHelp to build. Just something to be aware of, and I wish I knew before I was forced to do wholesale moves and renames.