tagging contents in structured FM?

[s_oehlert]

Dear all,

my boss has asked me to find out whether or not a certain problem may be solved through using the structured FrameMaker. We will finally be introducing FrameMaker in our documentation department and i do have some previous experience working with it but I have never worked with the structured one.

We would like to create technical documentation for our software products through a tool which allows tagging contents within chapters of our documentation, making it possible to assemble customer-specific documentation. My boss' idea was that he would like to be able to create tags for different contents within a chapter which indicate the software version the particular content (e. g. a new table or a new button within an existing operation) has been created for so that in the case a customer would like to learn about any changes introduced in a newer version compared to an old one we would be able to somehow assemble a documentation that only contains the contents which have been added for this particular software version or update or patch, neglecting any other contents from the chapter they are usually located in (I very much hope this makes sense to you, I don't know how else to describe it).

Since I have no experience with the structured FrameMaker I would greatly appreciate any answers giving me an idea of the possibilities of structured FrameMaker regarding this issue.

Thank you for your help!

[Russ Ward · Accepted solution]

s.ouflert,

The answer is a postive yes, although you must be willing to add a new layer of sophistication to your workflow and learn how to use it properly. Structural markup was really designed for this purpose... to add metadata (or "tagging" as you say) to content, such that automated processes can do work for you (like "assemble documentation").

There are two reasonably direct routes to your goal and any myriad of other possiblities if you would like to really get in deep and build your own tools/processes:

- DITA - Out of the box, FrameMaker supports authoring to the DITA standard, including all the content reuse mechanisms that would benefit you such as text inset and conditional text features, all using structural markup to identify and manage information during authoring and publishing (that is, document assembly).

- A custom structure definition using other plugins - If you don't need the complexity of DITA or its topic-level modular reuse philosophy, you can use plugins such AXCM and InsetPlus with any structure definition for very heavy-duty single-sourcing. You can read more about them at www.weststreetconsulting.com. Disclaimer - I own West Street but I'm happy to say that those two plugins are completely free.

Whatever route you choose, I'd like to emphasize whole-heartedly that structured documents should be at the core. FrameMaker has features such as conditional text and text insets that work on unstructured files, but these technologies are very old and fully obsolete. With any serious level of reuse, they will cost you as much in aggravation and maintenance as they will provide benefit. Look towards structure... it is the path towards allowing the computer to do the work for you.

Russ

[s_oehlert]

Hi Russ,

thank you for your answer! I will definitely have to book a class on that, i believe. It sounds a little complex to me but i do agree that the extra input needed for structured elements might save me work at a later point, plus this sounds exactly like what we are looking for. Do you mind giving me an idea about the level of knowledge and more importantly understanding of XML structures (and everything that goes with it) i would have to bring into this to be able to seriously work with it? Would I have to create any myself, would i have to go deeper into that matter to be able to fully use the structured FM? I happen to not have any experience in that field and I'm fearing it might be too complicated in the end. Although now that i know its possible, I guess there is no way out anymore

Again, thank you for your answer and maybe you can help me out once more (although i wouldnt guarantee it's the last question i might have...)

Cheers, Sandra

[Russ Ward]

Hi Sandra,

Your new questions are not so easy to answer . The amount of knowledge you will need really varies with extent of your end goals, which is unknown to me and probably unclear at best to you. This is the type of thing where processes and workflows evolve as your knowledge grows. You never really know where it is going to take you when you start out.

I would say that for a complete newbie, it can take weeks or months to really get comfortable in a structured environment. If you choose to build your own structure definition(s), then it can take longer, because you become a "developer" as well as a user. Having said that, I would encourage you not to be intimidated, because even the smartest gurus among us started where you are. I like to think that I understand structure pretty well by now, but there was a day that I sat in front of FM with nothing but the Structure Developers Guide, without much of a clue what XML is and what it is any good for.

Some people take a class, some just learn on their own. For many, this is just something that they gradually learn while doing their normal work, then begin to apply the concepts as they become within reach. One of the reasons that FrameMaker is good for learning structure is that it has an unstructured environment that you can continue to use while learning and gradually migrating. Since you imply that you are not using FM at all right now, I'd say it would probably be optimal for your department to jump straight into structured FM, because that helps alleviate the need to migrate later. However, if no one knows what they are doing, you might have to get some training if you want to do it in the near future.

I have no idea what your timelines are, but I'd suggest that someone gets a copy of FM and starts studying while your normal documentation continues. At some point, that someone should begin to see light and be able to plot a new structured strategy.

Good luck with this. If you are diligent and successful, there is a side benefit... your resume will begin to shine. Most tech writers put bullets like "wrote and edited documentation for such-and-such product, meeting deadlines and collaboration with SMEs" etc. etc.  That's fine, but it will never be able to compete with "Led implementation of a new structured workflow, allowing a significant increase in volume while also improving quality, all without additional staff", etc.

Russ

[s_oehlert]

Hey Russ,

thank you for your encouraging words, i do feel a little intimidated especially since me and XML do not exactly get along well, so far I always got around having to deal with it too much. Since I am also kind the only technical writer for my team it will probably be tough to fight through all by myself but you are right. The reward will eventually be a valuable addition to my resume. I started here 6 months ago and I guess I should be a little proud that during this time I improved documentation and was allowed to now FINALLY bring all contents over into FM sometime next month - documentation here used to happen in MS Word and its no fun at all.

Thank you for your support. I will do my best and I hope I will succeed.

Sandra