Re: [Framers] Starting DITA 1.2
Further to Scott's excellent advice: There are two separate issues here. One is DITA, and the other is structured authoring in FrameMaker. Of these, you should tackle the latter first. DITA is only one of the possible structures that you could use; the important first step is to bring your mindset to think in terms of structure as well as content. I am very grateful for a course that I attended many years ago on structured writing. On that course, having determined what our document structure should be, we simply used paragraph and character formats to define it by making full use of the "Next Pfg Format" property in the Paragraph Designer. So you should constantly be asking yourself, "What IS this?" as well as "What should it say?" From your original post, it sounds as though you already have the concepts of structure in your existing manuals - consistent use of paragraph formats, and so on. Having got that mindset under control, it was relatively easy to ensure that all new content was written in a structured way, still using unstructured FM. And that, in turn, made it easier to transition to structured FM later on. My advice would be to try writing some sample topics using the default DITA 1.2 application that is supplied with FM. (Caveat: My latest version is FM11, so I'm assuming that it is the same in newer versions.) Another important piece of advice (IMHO): Forget about XML for the time being. You can use DITA or any other structure without having to convert it to XML. I did that for a couple of years before even attempting to create XML. XML output is not without its own challenges, which you don't need at this stage. Since you are documenting programming commands, most of your topics will be DITA topics. You can wrap these in higher-level topics, keeping them all in one document. That is a whole lot easier than creating hundreds of standalone topic files - that can come later on. So forget about ditamaps for now. I hope this helps. Some versions back Adobe supplied with FM a structured authoring "cookbook", which was a tutorial with a set of files that you could work on. It was a great learning tool. Unfortunately, in their wisdom they discontinued it, but someone on the list may be able to supply you with it - I think it was pre-FM9. Regards, Roger On 27/06/2018 19:34, Scott Prentice wrote: Hi C2... That's a big question. Not one that can be answered properly via email. First .. read up on basic DITA concepts. Don't focus on what you want to do with it and how you can change it. Learn the fundamentals of DITA and structured authoring in FrameMaker. Here are a couple places to start (other people will likely have other ideas too) .. - http://www.publishingsmarter.com/resources/books-and-articles - https://www.scriptorium.com/learning-dita/ Also .. you may want to get on the framemaker-dita (Yahoo) maillist, you may get more help there. When reading about DITA concepts, don't worry about finding information about FrameMaker and DITA .. the concepts apply equally to all editors. Once you learn the basics of the topic and map models, you can focus on how you work with those models in FrameMaker. Similarly, you can learn about structured authoring in FrameMaker without focusing on DITA. DITA is just one model that you can use in FrameMaker, the basics of structured authoring in FrameMaker are the same regardless of the model. There are FM/DITA specific issues, but once you need to worry about that you'll be further down the path. Once you've learned a bit about DITA and start to feel comfortable creating basic topics and maps, you may want to consider trying to modify the elements and model .. try to avoid that as long as possible. Just work with what's there .. really. You'll be better off. In order to modify the model you should create your own structure application then modify that. Don't modify the default structure applications in FrameMaker. You *will* break things (everyone does), and if you don't have the default apps available to use, you'll be in trouble. Take this slow, and you'll find that DITA can be very powerful .. just don't try to rush things. Cheers, ...scott On 6/27/18 11:04 AM, cuc tu wrote: Hello Frame-users, I’m not familiar with structuring authoring, so hoping to get some guidance on creating DITA reference topics of programming commands. I'm spending a lot of time searching for help and not getting very far for the time I'me spending. First, I wonder if there are good samples to review of something similar. Next, I’m unsure of what would be an appropriate high level element structure. My main question is how should all the content blocks be structured and under what elements? From my perspective, is the whole chapter wrapped inside a reference element, with more nested reference elements for each main command grouping, and then each command yet another nested reference el
Re: [Framers] Starting DITA 1.2
I found no new-user resources for structured FrameMaker when I looked for them a few years ago. Adobe seems to presume that anyone who's going to use it will hire a consultant or something. https://forums.adobe.com/thread/939735 I suggest you look at Oxygen XML Author. On Wed, Jun 27, 2018 at 11:04 AM, cuc tu wrote: > Hello Frame-users, > > I’m not familiar with structuring authoring, so hoping to get some guidance > on creating DITA reference topics of programming commands. I'm spending a lot > of time searching for help and not getting very far for the time I'me > spending. ... ___ This message is from the Framers mailing list Send messages to framers@lists.frameusers.com Visit the list's homepage at http://www.frameusers.com Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/ Subscribe and unsubscribe at http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com Send administrative questions to listad...@frameusers.com
Re: [Framers] Starting DITA 1.2
Hi C2...
That's a big question. Not one that can be answered properly via email.
First .. read up on basic DITA concepts. Don't focus on what you want to
do with it and how you can change it. Learn the fundamentals of DITA and
structured authoring in FrameMaker. Here are a couple places to start
(other people will likely have other ideas too) ..
- http://www.publishingsmarter.com/resources/books-and-articles
- https://www.scriptorium.com/learning-dita/
Also .. you may want to get on the framemaker-dita (Yahoo) maillist, you
may get more help there.
When reading about DITA concepts, don't worry about finding information
about FrameMaker and DITA .. the concepts apply equally to all editors.
Once you learn the basics of the topic and map models, you can focus on
how you work with those models in FrameMaker. Similarly, you can learn
about structured authoring in FrameMaker without focusing on DITA. DITA
is just one model that you can use in FrameMaker, the basics of
structured authoring in FrameMaker are the same regardless of the model.
There are FM/DITA specific issues, but once you need to worry about that
you'll be further down the path.
Once you've learned a bit about DITA and start to feel comfortable
creating basic topics and maps, you may want to consider trying to
modify the elements and model .. try to avoid that as long as possible.
Just work with what's there .. really. You'll be better off.
In order to modify the model you should create your own structure
application then modify that. Don't modify the default structure
applications in FrameMaker. You *will* break things (everyone does), and
if you don't have the default apps available to use, you'll be in trouble.
Take this slow, and you'll find that DITA can be very powerful .. just
don't try to rush things.
Cheers,
...scott
On 6/27/18 11:04 AM, cuc tu wrote:
Hello Frame-users,
I’m not familiar with structuring authoring, so hoping to get some guidance on
creating DITA reference topics of programming commands. I'm spending a lot of
time searching for help and not getting very far for the time I'me spending.
First, I wonder if there are good samples to review of something similar.
Next, I’m unsure of what would be an appropriate high level element structure.
My main question is how should all the content blocks be structured and under
what elements? From my perspective, is the whole chapter wrapped inside a
reference element, with more nested reference elements for each main command
grouping, and then each command yet another nested reference element? I know
Frame limits the valid elements, but there are so many choices.
Our manuals have a common unstructured layout, similar to the default FM
document. The programming chapter of commands simply has a title, H1, text
description and a bullet list of links to all H1 sections. Each H1 section
describe its group of commands, then we use the command syntax as a heading
followed by a series of heading run-ins for each relevant program item that
needs to be described. For example:
Chapter title
H1 Intro
Body description
links
Calculate Subsystem
Text description of this system. May include bullet lists, tables, etc.
:CALCulate:POWer:LIMit {DBM}
:CALCulate:POWer:LIMit?
Title: Power Limit
Description: Sets and queries the amplitude power limit.
Parameters: {DBM}
Query Return: Numeric (dBm)
Default Value: 10 dBm
Default Unit: dBm
Range: -200 dBm to 200 dBm
There will be many subsystems and thousands of commands. They each have various
items to describe, not all exactly the same set.
I’m looking at a DITA 1.2 reference topic under the software domain, since I found the cmdname
element. Where are the DTD and EDD and other support files for this topic type? I searched the program
files for all .DTD and none of them have that element name (they didn’t have anything I expected).
Also, the saved XML file specifies: http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com
___
This message is from the Framers mailing list
Send messages to framers@lists.frameusers.com
Visit the list's homepage at http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com
[Framers] Starting DITA 1.2
Hello Frame-users,
I’m not familiar with structuring authoring, so hoping to get some guidance on
creating DITA reference topics of programming commands. I'm spending a lot of
time searching for help and not getting very far for the time I'me spending.
First, I wonder if there are good samples to review of something similar.
Next, I’m unsure of what would be an appropriate high level element structure.
My main question is how should all the content blocks be structured and under
what elements? From my perspective, is the whole chapter wrapped inside a
reference element, with more nested reference elements for each main command
grouping, and then each command yet another nested reference element? I know
Frame limits the valid elements, but there are so many choices.
Our manuals have a common unstructured layout, similar to the default FM
document. The programming chapter of commands simply has a title, H1, text
description and a bullet list of links to all H1 sections. Each H1 section
describe its group of commands, then we use the command syntax as a heading
followed by a series of heading run-ins for each relevant program item that
needs to be described. For example:
Chapter title
H1 Intro
Body description
links
Calculate Subsystem
Text description of this system. May include bullet lists, tables, etc.
:CALCulate:POWer:LIMit {DBM}
:CALCulate:POWer:LIMit?
Title: Power Limit
Description: Sets and queries the amplitude power limit.
Parameters: {DBM}
Query Return: Numeric (dBm)
Default Value: 10 dBm
Default Unit: dBm
Range: -200 dBm to 200 dBm
There will be many subsystems and thousands of commands. They each have various
items to describe, not all exactly the same set.
I’m looking at a DITA 1.2 reference topic under the software domain, since I
found the cmdname element. Where are the DTD and EDD and other support files
for this topic type? I searched the program files for all .DTD and none of them
have that element name (they didn’t have anything I expected). Also, the saved
XML file specifies: http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com
