Highlighted

Bad instructions in the FrameMaker 2015 Help File

Participant ,
Jun 25, 2015

Copy link to clipboard

Copied

Having recently installed FrameMaker 2015, I reviewed the help file, specifically looking for updates concerning structured projects. In years past, I recalled that the instructions for constructing an EDD, DTD, and application had confusing errors, though I didn't know enough to make sense of things until reviewing various online seminars.

So as a means to identify workflow changes in the current release, I started reading the following sections:

FrameMaker (2015 release) >> Structured authoring >> Getting started with structured applications

In particular, the following sub-sections have issues:

  • Create an EDD
  • Create a DTD from an EDD
  • Build a structured application
  • Test XML roundtripping

For the section: Create an EDD

Under "Change the Body tag definition," there is a reference to a structured_proposal.fm file in the first paragraph. However, this file doesn't exist until a couple pages later in the procedure, which is quite confusing. I decided to ignore that paragraph.

To fix that paragraph, the description probably needs to be removed, but anyone struggling with it, imagine that the paragraph leads with:

Later in this section, you will test your EDD by creating a structured_proposal.fm file. With that file, you will be able to select Format > Paragraphs > Designer and change the default definitions for the Body and Heading1 paragraph tags. For example,...

For the sub-section: Test the EDD

Just prior to this section, there is a "Test the results" section that again refers to the structured_proposal.fm file. Again, worthwhile to just ignore that section, in particular the link for a completed EDD, since the link is broken.

Now, for the section title, "Test the EDD," think of this titles as, "Test the EDD in a blank structured_proposal.fm file."

And for point (1), which reads, "Create a new, blank, portrait document by selecting File > New > Document, and then click Portrait." To this line, append the following: Save the file as structured_proposal.fm

For the section: Create a DTD from an EDD

Remove this section. The procedure is already covered in the subsequent section, "Build a structure application."

Worse, this section makes reference to, "...the XML application that you created in the previous section." However, this is not true. The application is created in the next section.

For the section: Build a structured application

This procedure has sections in the wrong order because you can't create the DTD until after the application. (If you don't believe me, then try the procedure.)

To fix this section, the following two sub-sections:

  • Create a DTD
  • Create a structured template

...should be moved TO AFTER the Configure the structured application, and BEFORE Copy the application files.

There's also a problem with the Test XML roundtripping section, but I'm going to describe the issue in another post, since this post is getting long, and I need help to interpret what the roundtripping description is saying.

Anyhoo, hope this helps anyone trying to understand the FrameMaker documentation. Adobe needs to task a technical writer to improve the overall clarity. Much of the current issues appear to be related to shuffling sections around without proofing the workflows, and anticipating confusing descriptions.

TOPICS
Structured

Views

251

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more

Bad instructions in the FrameMaker 2015 Help File

Participant ,
Jun 25, 2015

Copy link to clipboard

Copied

Having recently installed FrameMaker 2015, I reviewed the help file, specifically looking for updates concerning structured projects. In years past, I recalled that the instructions for constructing an EDD, DTD, and application had confusing errors, though I didn't know enough to make sense of things until reviewing various online seminars.

So as a means to identify workflow changes in the current release, I started reading the following sections:

FrameMaker (2015 release) >> Structured authoring >> Getting started with structured applications

In particular, the following sub-sections have issues:

  • Create an EDD
  • Create a DTD from an EDD
  • Build a structured application
  • Test XML roundtripping

For the section: Create an EDD

Under "Change the Body tag definition," there is a reference to a structured_proposal.fm file in the first paragraph. However, this file doesn't exist until a couple pages later in the procedure, which is quite confusing. I decided to ignore that paragraph.

To fix that paragraph, the description probably needs to be removed, but anyone struggling with it, imagine that the paragraph leads with:

Later in this section, you will test your EDD by creating a structured_proposal.fm file. With that file, you will be able to select Format > Paragraphs > Designer and change the default definitions for the Body and Heading1 paragraph tags. For example,...

For the sub-section: Test the EDD

Just prior to this section, there is a "Test the results" section that again refers to the structured_proposal.fm file. Again, worthwhile to just ignore that section, in particular the link for a completed EDD, since the link is broken.

Now, for the section title, "Test the EDD," think of this titles as, "Test the EDD in a blank structured_proposal.fm file."

And for point (1), which reads, "Create a new, blank, portrait document by selecting File > New > Document, and then click Portrait." To this line, append the following: Save the file as structured_proposal.fm

For the section: Create a DTD from an EDD

Remove this section. The procedure is already covered in the subsequent section, "Build a structure application."

Worse, this section makes reference to, "...the XML application that you created in the previous section." However, this is not true. The application is created in the next section.

For the section: Build a structured application

This procedure has sections in the wrong order because you can't create the DTD until after the application. (If you don't believe me, then try the procedure.)

To fix this section, the following two sub-sections:

  • Create a DTD
  • Create a structured template

...should be moved TO AFTER the Configure the structured application, and BEFORE Copy the application files.

There's also a problem with the Test XML roundtripping section, but I'm going to describe the issue in another post, since this post is getting long, and I need help to interpret what the roundtripping description is saying.

Anyhoo, hope this helps anyone trying to understand the FrameMaker documentation. Adobe needs to task a technical writer to improve the overall clarity. Much of the current issues appear to be related to shuffling sections around without proofing the workflows, and anticipating confusing descriptions.

TOPICS
Structured

Views

252

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Jun 25, 2015 0

Have something to add?

Join the conversation