I've been using FrameMaker for a long time now, though always in not-structured mode.
I'm wondering if I should go the structured way, and this for several reasons:
- the devs in my company use Doxygen to generate the API documentation. My company still wants "good-looking" PDF manuals. So I thought structured FM could be an asset to retrieve the XML/HTML code and import it in structured FM. Are you using such a solution ? What solution is it ?
- my company wants to introduce online help, so the input text could be structured FM text right ?
- my company recently merged with another company, which means that all the graphical template of all manuals must be edited. I think that having the manuals in structured format would allow me not to be bothered by this any more.
- only a small portion of the manuals have overlapping content.
- I am not concerned with translations/maintaining doc in several languages. We do not use this.
What is your opinion ?
Thanks in advance.
I'm going to watch this thread with interest, Tulla! I've been a happy Framer since FM5.5, and can fairly say that my clients have always been pleased with the appearance of the results. I'd love to get back to working with structured documents, and hope to move at least some projects to DITA; benefits will include greater consistency, and easier management of small updates in large documents.
But … after looking at structured mode every now and then in FM9 and FM10, I don't think that's what I'll be using – despite the powerful, helpful structure map. It's all a question of looks! the default output is way different from what I'm used to delivering, and the user interface with its fuzzy Minion is uncomfortable. With an easy/easier way to map structure elements to "my" styles for both input and output, I'd stay; but when I'm confronted with a on-screen layout that makes my toes curl and default output that seems to come from decades ago, I'm minded to look elsewhere. (interestingly enough, my precursor watched experiments with Doxygen wither and die just because people weren't happy with the appearance of the output) Drop me a note – communicator dot ngn at gmail – if you'd like the name of my preferred IDE; I feel a bit diffident about suggesting/recommending non-FM solutions in the FM forum ;-}
So – if anyone says all this goes away in FM 11, I'll have to smile politely and refer them to the corporate beancounters: but I'll be interested to hear what people have to say about your questions, because I think structured authoring per se is something to be encouraged. It's also liberating, because it gives you a secure foundation and helps you concentrate on content.
[ps] I won't mind being told my reactions to structured FM are completely unfounded, based on fundamental ignorance and so on and so forth: I'm here to learn … and I'm sure contributors to this august forum will be gentle and constructive however much they just want to reach for the hatchet <rofl>
As usual, when migrating from one technology to another, there are benefits and drawbacks.
Migration of "unstructured" content to XML can be an asset, but it also can be a disease.
If you work with HTML or XML in your company anyways, moving to structured authoring and XML based documents nearly always is an asset.
It takes time, money and enthusiasm though to walk down this road.
The benefits are clear: Separation of content and layout, possible reuse, "easy" transformation between outputs (pdf, HTML, stuff), "guided" authoring and many more.
The drawbacks are: maintainance of your structure, spending more or less time to fully adopt the new system, sometimes it's more time consuming than "just write it down".
There are some critical steps, when defining your new workflow. If you do it wrong there, the whole thing can become a nightmare. If you do it right, it can up your productivity in a way you never dreamed of.
The prejudge, that structured authoring produces ugly output is just wrong. True, the default layouts are out of discussion, but there's no reason to use them anyways. The ugly layouts are Framemaker specific anyways, as it is much harder to get a nice layout, compared to what you can do in InDesign. But if you put some time in it (or simply reuse your old layouts), you can even get nice layouts in Frame.
You have to really want to use a XML workflow, and you need to put some thought and effort in the migration. Otherwise you will fail badly and struggle with an unwanted system, that does more hinder than help you.
I've been an happy (unstructured) Framer since 3.0 (1993). I didn't see any good reasons to move to Structured FrameMaker until a good, generic "off-the-shelf" structured application became available. Setting up a custom structured application from scratch could easily take weeks or even months of development work: developing DTDs, EDDs, setting up read/write rules, designing templates etc. That's the reason why we only used Structured FrameMaker to write documentation for large corporations, such as Van Hool, Atlas Copco and Alcatel. But this all changed (a bit) when Scriptorium released DocFrame, a (more or less) standardized, generic structured application. You could just buy it, install it and create structured .fm files in a matter of minutes. And then, it all changed dramatically in 2005 - 2006 when DITA became an official OASIS standard and the DITA editors were being developed. With DITA, you create XML files, which can also be edited with other tools than FrameMaker. This opens up a lot of opportunities to reuse content and collaborate with other "content developers", such as developers, colleagues, partners etc.
So here are my answers to your questions:
"- the devs in my company use Doxygen to generate the API documentation. My company still wants "good-looking" PDF manuals. So I thought structured FM could be an asset to retrieve the XML/HTML code and import it in structured FM. Are you using such a solution ? What solution is it ?"
Yes, I am, and the solution is DITA. DITA has the required elements to write API documentation:
I'm not familiar with Doxygen, but I've seen some discussions about it in the Yahoo dita-users group:
So, I guess the Doxygen could be transformed to DITA XML, which can then be published to PDF via FrameMaker. If you still want good-looking PDFs, created from DITA-sourced content, use Leximation's DITA-FMx plugin. This is an example of a PDF file created from DITA-sourced content (feel free to download it):
"- my company wants to introduce online help, so the input text could be structured FM text right ?"
Correct, but I'd use DITA XML files instead of binary, structured .fm files. With DITA XML files, you have a wider range of help authoring tools and help compilers: the free DITA Open Toolkit (integrated in oXygen XML Author and XMetaL), but also RoboHelp, MadCap Flare, WebWorks ePublisher, DITA2Go and others.
"- my company recently merged with another company, which means that all the graphical template of all manuals must be edited. I think that having the manuals in structured format would allow me not to be bothered by this any more."
Well, you will definitely have less templates to maintain. In unstructured FrameMaker, each FrameMaker document can function as a template, and it is almost impossible to keep the formatting in all those files consistent (File > Import > Formats, you know). With DITA, you basically use two templates: one for authoring the DITA topics and one for generating FrameMaker files (and then PDFs) from your DITA maps. Once these templates have been set up, there's no need to import formats anymore.
"- only a small portion of the manuals have overlapping content."
OK, so there's limited potential for reuse across documents, but maybe a lot of content can be reused within a manual? Just look at your manual and try to find reused sentences or phrases, for example "Proceed as follows", "Do one of the following" etc.
In unstructured FrameMaker, you use variables, text insets and conditional text to reuse content. In DITA, you have similar mechanisms: conrefs ( text insets), keyrefs (= variables) and ditaval (= conditional text). DITA conrefs, however, work better than FrameMaker text insets, because you don't have to save each piece of reusable content in a separate file. You just create one file (a "conref library") in whch you put all your reusable content, and then reference that content into the actual topics of your manual.
- I am not concerned with translations/maintaining doc in several languages. We do not use this.
What is your opinion ?
See my comments above.
Adobe-Certified FrameMaker Instructor
Pleased – or even relieved ;-} – to see general agreement with my broad ideas: structure (especially DITA) good, default FM output … less good.
Of course it's wrong to blame structure for unbeautiful layout, and I hope I didn't suggest it; but to put it brutally, if I stayed with FrameMaker I would have to spend a lot more time struggling to get acceptable output than I would converting my source to DITA. That's not efficient, and wouldn't be acceptable to my paymasters.
Of course it's wrong to blame structure for unbeautiful layout, and I hope I didn't suggest it;
But you are Niels.
Structure has nothing to do with format. And this is true of DITA. There is nothing in DITA that makes a pretty format. If you are talking about the format that comes from using DITA in FrameMaker, then you are talking about the default formatting FrameMaker supplies for DITA applications, not the formatting supplied by DITA.
The same holds true for the structured applications supplied by FrameMaker. If you do not like the look of a FrameMaker-supplied app, it is not the structure that it is the problem but the underlying template that FrameMaker supplies with it.
In my opinion, two of the things that a good about structured writing are freeing the writer from having to remember formatting issues and providing consistency across a document set.
I agree that it takes more than a passing effort to create beautiful formatting for structured doccuments, but the effort is worth it, especially if one is creating a corporate look. If your EDD links structures to character and paragraph styles, then changing formatting is as easy as changing your styles. Creating a structured template for a one-off document is, I agree, a waste of time.
Even structured documents in FrameMaker can be overridden to change the look, but I would avoid this. A well-constructed template should work well in the vast majority of documents.
By the way, MY structured documents ARE beautiful...even without overrides.
As Van says, you might be harbouring a misconception about creating structured content and publishing structured content. You can create very aesthetic output from structured content using FM (it's all in the templates), especially using add-ons such as Scott Prentice's DITA-FMx, or you can create bland looking stuff via the default FM supplied templates or the Open Toolkit by using them "out-of-the-box" with no customization.
The process is now truly separated into separate steps; authoring and then publishing. Even without going the structured route, I would wager that you're using templates that have been created specifically for your (company's) publishing requirements rather than just the canned FM templates supplied in Templates folder.
If you think you're solving your structured formatting woes by abandoning FM, we'll see you back here soon!
Formatting of structured output is one of structured FM's strongest points, and large corporations do full-blown FM installs and implementations for the very reason that FM outputs structure at a higher degree of customization, and for a fraction of the cost.
No, I'm not saying that "structured equals ugly", nor that FM wouldn't be the bee's knees when it comes to creating structured content – I'm just saying that when I fire up FM and open a (beautifully!) structured DITA file, what I see out of the box comes as an unwelcome shock to the extent of being a distraction. The phrase "large corporations do full-blown FM installs and implementations" is light-years away from the context at my desk. I'm the only FM user, no-one has yet got as far as customising anything … and if I hope to win company support, I've got to be able to show acceptable output as one of the benefits.
I'm going to have difficulty getting approval for any additional expenditure on plug-ins, but hope I'll be able to negotiate at least some time to struggle with the (?) DITA EDD. I did take two days of training five or six years ago, but all I retain is a strong impression that it's not as simple as a mapping table "element A uses myStyle B" … Who can suggest some good books? If I do reach the stage of having woes, it'll feel like progress!
@Arnis – I think you win your wager, but apart from a couple of enjoyable contracts using BookMaster it's always been me that's had to set up the stylesheet ;-}