Documenting XML files in FrameMaker

[susmur]

Hello Framers,

the software I'm documenting uses XML files as configuration files. I describe these files in tables, but I'm not happy with it. The manual pages are in portrait orientation and I frequently run out of space because the element names can be so long. This also prevents me from documenting the files in a consistent manner. On the other hand, I wouldn't like to switch from portrait to landscape and vice versa. Is there a better way to document these XML files? Maybe using additional software the output of which can be imported into FM?

Any help would be appreciated

Susanne

[Michael_Müller-Hillebrand]

Susanne,

Are you working with structured or format-based documents?

I have a use case where a nice visual representation was required by the customer, it is shown here:

http://cap-studio.de/wp/index.php/2009/11/wie-ist-das-umgesetzt/

It is really comfortable with structured FrameMaker, because you don’t need tables... Screenshots are in the post, a PDF sample is linked as well.

Maybe you can show us examples of what you want to achieve?

- Michael Müller-Hillebrand

[susmur]

Michael,

thank you for your reply.

I'm using unstructured FrameMaker 9. In the XML files that need documentation, the user needs to edit elements and attributes (with some files, only elements, with other files, only attributes, in some cases both). I've attached a screenshot of what I'm doing at the moment (which is actually not what I want to achieve). Since the width of the page is limited, I currently use a different table layout depending on what has to be edited in the XML file, but I'd prefer a consistent table structure.

I know that there are numerous tools that generate XML file documentation more or less automatically. But so far, I haven't found a tool that meets my requirements. The problems I have with these tools are the following ones:

• Most of the time, I only have an XML file. I may have a DTD or should be able to get one from developers. XML documentation tools seem to expect an XML schema file.
• The generated documentation is extremely long, and I'd like to keep the description as concise as possible.
• Usually, the output is in HTML format which is hard to import into FrameMaker.

Thanks for any suggestions.

Susanne

[Michael_Müller-Hillebrand]

Susanne,

The sample shows a lot of wasted paper as well as redundancy. The only column with predictable width is the second column (Required - Yes/No). The rest of the material is not suited for tabular presentation. I would rather work with different indentations.

Or, even better and since you are not satisfied with the solution at all, I would step back and try to find out what the readers are mostly looking for and redesign the material according to the real requirements. I have seen many cases, where software documentation was structured according to the developers’ view and not the users’ view. The developer can easily live with generated documentation, but does that help the user?

- Michael Müller-Hillebrand

http://cap-studio.de

[susmur]

Thanks. I'll try an intended style.