Phase 2: Development

Development plan

Although we are at a very early stage in the project, W2U together with the client will put together a development timeline. As with all other projects, it is hard to predict the future, but with substantial experience from similar projects, W2U can make very educated estimates of the project timeline.

Architecture meeting

With the pre-analysis report and requirement specification in our hands, we are ready to get our hands dirty! Well, not quite – first, we need to develop our Flare architecture strategy. W2U calls a meeting with all the key stakeholders in the process. This is probably the most important meeting in the entire development process. We discuss how we can build an architecture – both in Flare and the source control system – which can be expanded and is suitable for translations, as well. The meeting ends up in an architecture drawing which is also included in the final project documentation.

First Flare project

By now, we are really ready to go. Together we create our first real Flare project which later becomes the template for all our Flare projects. Typically, we choose a representative, medium-sized project which will help us make the decisions we did not anticipate earlier. At this early phase, we can already start defining some of our variables, conditions and even snippets (reusable chunks of content). Most clients are not starting from scratch, so we import some of the existing content to start building the TOC structure. If we are starting from scratch, we write some topics and try to shape our first topic templates (see further below).

Integration test

Flare is not a standalone system, of course.  In every company, Flare has to integrate with other systems. Typically, we integrate with the following two systems:

  • Source Control System – Flare integrates completely with Team Foundation Server, Visual SourceSafe, Subversion, Git and Perforce (plus 3rd party systems via plug-in dll)
  • SQL Server – The Madcap Lingo localization tool relies on an SQL Server where the Translation Memory and Termbase reside

With more advanced projects, we also integrate with various programming and automation tools, content databases, CMS systems, etc.

Conversion of legacy content

Almost every new Flare client has legacy content residing in other authoring systems. When moving from the existing system to Flare, much of this legacy content needs to be converted into Flare. Luckily, Flare has a very strong and flexible import filter for the following formats:

  • Microsoft Word
  • Adobe Framemaker
  • Adobe Robohelp
  • DITA (XML) files
  • HTML files

With these filters, you can import almost any type of existing content out there. The Microsoft Word and Framemaker filters are especially strong, as you get the chance of mapping the paragraph and character styles from the old environment to the new.

W2U has extensive experience in converting Word files and Framemaker projects. W2U collaborates with leading experts of Framemaker and XML/HTML to assist clients in a smooth transition to Flare.

The conversion of legacy content is a one-time job. This is why many W2U clients choose to let us do the conversion, instead of spending many valuable authoring hours on pure conversion tasks. When users try to convert themselves, they will sometimes end up in spending way too much time on this task. Let the experts do the job for you!

CSS design

One of the most central elements of a Flare project is the Cascading Stylesheet (CSS). This is where you define the colors, the styles and the behavior of the content in your topics. Building a powerful and flexible CSS file is not trivial, if you do not have any prior CSS knowledge. This is why many of our clients choose to let W2U either design the CSS or assist in the CSS architecture setup. The CSS model has so many features and advantages that it takes an expert to build the perfect CSS.

Although you can import all the styles you have in Word or Framemaker, it is a very good idea to let us help in order to minimize the number of styles – and thus minimize the maintenance of the CSS file. Also, the single sourcing power of Flare needs to be addressed in the CSS. Some styles are for print only, some are for online help only and others are for both formats.

Once the CSS file has been done, it can be linked into all your Flare projects so that you only have to maintain one CSS.

Flare project template

During the development phase, we identify the elements of the first Flare project which should go into our Flare project template. This template has a dual function:

  • It serves as a template for new Flare projects
  • It becomes the Global Project in a family of Flare projects

The Global Project Linking feature in Flare allows you to link all the shared elements in the Global Project to the child projects. For example, if you have 20 different Flare projects, you only need to maintain the shared elements in the Global Project. That’s what we call single sourcing. Examples of shared elements would be the company logo, the company address, the product variables, shared warnings, etc.

Flare topic templates

Flare builds on the concept of topic based authoring. This means that all your content is broken down into small chunks of information – the topics. A topic contains information on one subject only, it must be self-contained and able to stand alone. A topic can be presented in different ways – as online help, a page in a PDF, a page in an e-book, etc. In an online help system the topic must be able to stand alone, because the user may find it in a search and read it out of context. Basically, he does not know where the topic belongs in the structure.

This is where the topic templates come in. A topic template helps the technical communicator become more aware of what type of information he is conveying. The topic template also helps the reader because the topic structure becomes easily recognizable and easy to follow.

In technical documentation, we typically operate with three main content types:

  • The conceptual topic (What is…)
  • The procedural topic (How to)
  • The reference topic (lookup information)

When you define a topic template for each of these content types, you have typically covered 90% of all your content! This is why topic templates are very effective. Let W2U help you build your topic templates based on our experience with hundreds of Flare projects.

Branding

Every company wants it own branding to appear in online help, PDF files, printed documentation, etc. In Flare, we use skins (for online help) and Page Layouts (for print files) to design the framework around your content. Typically, we integrate your logo, taglines, company colors, etc. in the Flare design. With the flexible and open nature of Flare, you can change almost any element in the UI of your output. So, if you have a reasonable company design guide, we can assist you in making your output shine!

Prototype builds

Throughout the development phase, we make sure that our expectations are aligned in relation to the final output. So building prototypes of online help and PDF is very important for assuring that we are constantly on the right track. Technically, we help you build your Flare targets and use our checklist for the outputs.

Deliverables

Development plan
Architecture meeting
First Flare project
Integration test
Conversion of legacy content
CSS design
Flare project template
Flare topic templates
Company branding
Prototype builds

Phase 2: Development