Which structure format is best for user guides and why?

[Carefree_fact15C2]

I use Framemaker 7.2 structured to generate software user guides.

Currently I am trying out Framemaker 10. In the Structure folder of the Framemaker installation folder there are many different types of structures available. The XML - UserGuide structure looks nice, but does not have elements for note or warning boxes.

In general, which of these out of the box structures (found in C:\Program Files (x86)\Adobe\AdobeFrameMaker10\Structure) are advisable to take for user guides? and why? what advantages does each structure (Book, DITA, xdocbook, Online, etc.) bring?

I would be grateful for any help you can provide.

[Van Kurtz]

What is wrong with the structure you are now using in version 7.2? It will work in version 10.

[Carefree_fact15C2]

Thank you for your reply.

I could use the structure I'm using now, but it is quite an obselete custom structure. In general, I would like to understand the different structures available in version 10 and their areas of application better.

Moreover, I would like to know which structures in 10 would be advantageous for user manuals and why. (if there are no clear advantages, we won't buy the new version)

[Van Kurtz]

With the exception of DITA, to my knowledge, the structures that come with version 10 do not depend upon having version 10. They are just structures with EDDs that should work with almost any version of FrameMaker. If your only reason to get version 10 is to get the sample structures, you can download the trial version of 10 and transfer the samples to you Frame 7.2. If you do, be sure to check the structure apps file and copy the appropriate parts into your structapps file, making any obvious changes.

That is my take on it, but I will let others who have version 10 chime in on whether the samples can be used with Frame 7.2.

[Carefree_fact15C2]

Hello thx for your reply, sorry for my late reply - I got married at the weekend...

Good to know that I can use the sample structures in version 7.2. When I first started using Framemaker, the manuals back then were written in XML and Framemaker was useful to read them and structure them better. In the meantime, we don't use XML anymore and word would do the job just as well.

Still what I would like to know: what are the advantages of each of the sample structures in Framemaker for user manuals. Is there a tutorial video somewhere about this theme? or perhaps an overview of the sample structures with use cases including pros & cons?

[Russ Ward]

ABJB,

First of all, congratulations on your voluntary admission to prison. AH, WELL, ha-ha, we all know now that my wife doesn't read these forums

Back to the peripheral issue, your question is impossible to answer concisely, as it is rife with endless debate, personal opinions, and the influence of professional egos. The basic reason for this is because truly there is no one-size-fits-all answer. Each architecture and implementation is different, and each potential method is so extensible. What's more, a clever architect could take a suboptimal structure definition and turn it into a workflow miracle. So, there are many, many factors involved. The result is that you really have no choice but to experiment with the different possibilities and decide for yourself which makes the most sense.

I'll offer the following basic summary which I have tried to keep as objective as possible. I certainly have my own personal opinions, but I've done my best to leave them out. Marriage has helped me learn how to do that ALRIGHT OK I'll stop with that:

- DITA and DocBook were designed as "generic" standards that can be customized to suit a specific need, with DITA being especially strong in that area. As the name implies, DocBook was originally created to facilitate "book-like" publications, while DITA is stronger in the area of modularizing by topic, then assembling and reusing those topics. With the right stuff, though, you can use either standard for either methodology. I think it is clear, though, that DITA is the new fad and you'll find much more tool and community support for it. Given the choice between the two, I'd choose DITA because I like the structure definition better and the widespread industry support makes the content very portable indeed. For lots more in this comparison, you can Google DocBook vs. DITA.

- Other structures such as S1000D and MIL-spec DTDs are well suited for long document publishing but are specifically designed around some regulation from some industry or government. They are more rigid and specific in their semantics, which normally makes them a logical choice only if you are forced to comply with one of them.

- A structure definition like XHTML is good for specialized instances for when you need the respective output type to plug directly into some third-party process. For example, if you are developing web material, maybe it makes the most sense to export directly to XHTML. However, it should be noted that no structure definition prevents you from ultimately making any kind of XML, for example, a little bit of XSLT will give you very nice HTML from DITA, and there are free tools that can do it for you.

I hope this helps some. It is a very broad topic with no easy answer. Again, I suggest that you start poking around yourself and keep an open mind.

Russ

[Carefree_fact15C2]

Hey Russ,

Thanks for expressing your personal opinions - they are helpful for me. Btw, no plans to make a jail break yet, ha-ha, and nice to read that it has worked out well for you. I'm going to give DITA a try - any tips from your experience about starting points, dos and don'ts?

[Russ Ward]

ABJB,

I'm not the best to ask about DITA, because I don't use it personally. I've been content to use custom structure definitions through the course of my career. Any more, though, they look a lot like DITA because I like the logic of the topic DTD markup. However, as I have no use for topic-level reuse or the features of the Open Toolkit, I don't really ever use "real" DITA.

DITA and associated free tools (such as the toolkit) are enormously complex, so it is perhaps the most challenging choice for you to make. Maybe you could visit the Yahoo DITA users group and post a "getting started" question there, if nobody has anything more to add here:

http://tech.groups.yahoo.com/group/dita-users/

Good luck!

Russ

[Carefree_fact15C2]

Thanks Russ for all your help - so I've learnt that there is no "best" FM structure format for user guides, that it's more a personal preference, but all of your answers were very helpful.

I'm going to try out DITA, but at least for the foreseeable future I won't be trying out the toolkit, like you wrote this is far too complex for me.

As well as the yahoo groups that Russ mentioned, I'd also recommend the following link for anybody reading this who is also new to DITA

http://www.ditausers.org/tutorials/basics/Priestley_Intro/