DITA file naming conventions

[Andy Lewis]

Hi Jim,

DITAToo from iG5 Authoring Tools can do this. Check out DITAToo at
www.ditatoo.com and some interesting discussions in the DITAToo Community
group page on LinkedIn at
http://www.linkedin.com/groups/DITAToo-Community-3964604?gid=3964604&trk=hb_
side_g.

Best wishes,
Andy Lewis



iG5 Authoring Tools
+972 54 4605708
www.ig5authoringtools.com


LinkedIn http://il.linkedin.com/in/andylewis2003
Twitter http://twitter.com/andytelaviv

-Original Message-
From: framers-boun...@lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of Jim Owens
Sent: Thursday, November 03, 2011 8:05 PM
To: Roger Shuttleworth
Cc: framers at lists.frameusers.com
Subject: Re: DITA file naming conventions

 >   As far as possible, make sure the file name matches the title of 
the topic. So if your topic is "Inserting the Widget" then your file 
name would be "inserting_the_widget.xml". I realize this may cause 
problems later if the title changes, but that doesn't happen often and 
you can usually make the change to the file name without too much hassle 
(changing it in ditamaps, etc.).
 >

Since this has come up, I was wondering if any DITA-aware CMS offerings 
can present the topic title or map title for selection by the user, 
instead of the file name.  This would support the use of GUIDs for the 
file names, which would guarantee uniqueness, and allow users to adjust 
titles without having to manage ditamaps, related-links, or xrefs.

___


You are currently subscribed to framers as andylewis0 at gmail.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/andylewis0%40gmail.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

DITA file naming conventions

[Yves Barbion]

Hi hessiansx4

Some more tips:

   - Avoid spaces and special characters in file names, also in file names
   of graphics
   - Buy some tools and Framescripts to convert your unstructured Fm files
   to DITA: MIF2Go and some Framescripts to rename your topics and change the
   topicrefs in the ditamap accordingly
   - Buy DITA-FMx for enhanced DITA support in FrameMaker 10: you will be
   able to generate a PDF-ready FrameMaker book from your bookmap. The cover,
   frontmatter, table of contents, index and other generated lists will be
   added automatically in 1 go.
   - Get training and coaching. We can help you with the whole process.
   Feel free to contact me off-list if you're interested.


> Kind regards


-- 
Yves Barbion
www.scripto.nu
-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/e10e93d1/attachment.html>

DITA file naming conventions

[Jim Owens]

For what it's worth, the DITA Style Guide recommends using names that 
match the titles.

  It also recommends using the extensions .dita and .ditamap, instead of 
.xml. That way, you have more control over which tool opens the file, 
and you can distinguish the files from other xml files used in DITA.

On 2011-11-03 15:02, Roger Shuttleworth wrote:
> Hi Jim
>
> You make a good point about updating xrefs and related-links, as well 
> as ditamaps, when a file name changes.
>
> I have made good use of the map checking function in oXygen Author. 
> You open the map in Author, then run it through an automated checking 
> routine that will point out any problems such as missing files or 
> inappropriate href values.
>
> I sent a follow-up message to the original poster correcting my 
> recommendation to use folders named according to deliverables. I meant 
> to recommend using the product name, not the deliverable. Different 
> deliverables are created from a single pool of files, using different 
> maps; or perhaps using the same map filtered by ditaval.
>
> Thanks for your tip about GUIDs too. I will look more into that.
>
> Roger Shuttleworth
> Technical Documentation
> AV-BASE Systems Inc.
> 1000 Air Ontario Drive, Suite 200
> London, Ontario
> N5V 3S4
> Tel. 519 691-0919 ext. 330
>
> 
>

-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/7f94ff51/attachment.html>

DITA file naming conventions

[Roger Shuttleworth]

Hi Jim

You make a good point about updating xrefs and related-links, as well as 
ditamaps, when a file name changes.

I have made good use of the map checking function in oXygen Author. You open 
the map in Author, then run it through an automated checking routine that will 
point out any problems such as missing files or inappropriate href values.

I sent a follow-up message to the original poster correcting my recommendation 
to use folders named according to deliverables. I meant to recommend using the 
product name, not the deliverable. Different deliverables are created from a 
single pool of files, using different maps; or perhaps using the same map 
filtered by ditaval.

Thanks for your tip about GUIDs too. I will look more into that.

Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330
  _  

From: Jim Owens [mailto:jow...@magma.ca]
To: Roger Shuttleworth [mailto:rshuttleworth at avbasesystems.com]
Cc: framers at lists.frameusers.com
Sent: Thu, 03 Nov 2011 14:04:54 -0400
Subject: Re: DITA file naming conventions

 >   As far as possible, make sure the file name matches the title of 
  the topic. So if your topic is "Inserting the Widget" then your file 
  name would be "inserting_the_widget.xml". I realize this may cause 
  problems later if the title changes, but that doesn't happen often and 
  you can usually make the change to the file name without too much hassle 
  (changing it in ditamaps, etc.).
   >

  Since this has come up, I was wondering if any DITA-aware CMS offerings 
  can present the topic title or map title for selection by the user, 
  instead of the file name.  This would support the use of GUIDs for the 
  file names, which would guarantee uniqueness, and allow users to adjust 
  titles without having to manage ditamaps, related-links, or xrefs.

  ___


  You are currently subscribed to framers as rshuttleworth at avbasesystems.com.

  Send list messages to framers at lists.frameusers.com.

  To unsubscribe send a blank email to
  framers-unsubscribe at lists.frameusers.com
  or visit 
http://lists.frameusers.com/mailman/options/framers/rshuttleworth%40avbasesystems.com

  Send administrative questions to listadmin at frameusers.com. Visit
  http://www.frameusers.com/ for more resources and info.

-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/b6e6c357/attachment.html>

Re: DITA file naming conventions

[Scott Prentice]

The DITA-FMx/XDocs connector presents the topic and map files with both 
filename and title in either order.


Since we're on the subject of tools and file naming options ..

DITA-FMx provides numerous ways to automate the file naming for new 
files using building blocks that can be assembled in many ways. In the 
New DITA File dialog, you enter the title of the new file, and the 
filename can be generated from that text using one of 6 title-based 
building blocks. You can also use a building block that includes a 
unique ID (which matches the ID of the new topic being created). There 
are also building blocks for topic type, date, time, and others. All of 
these can be combined as well as restricted to a specific number of 
characters, as well as being able to include folder specifications (so 
your new files end up in the right topic-based folder, if you choose to 
go that route). Details are here ..


   http://docs.leximation.com/dita-fmx/1.1/?ditafmx_ref_newfileoptions.html

Personally, I prefer to use unique IDs for filenames, and only access 
the files through the map (where you see the topic titles rather than 
the filenames). This lets you keep all of the files in one folder and 
you never have to look at the file names. No matter what file naming 
convention you use (unless it's unique IDs), it breaks down and causes 
problems eventually.


Cheers,

...scott

--
Scott Prentice
Leximation, Inc.
www.leximation.com
+1.415.485.1892


Jim Owens wrote:
>   As far as possible, make sure the file name matches the title of 
the topic. So if your topic is "Inserting the Widget" then your file 
name would be "inserting_the_widget.xml". I realize this may cause 
problems later if the title changes, but that doesn't happen often and 
you can usually make the change to the file name without too much 
hassle (changing it in ditamaps, etc.).

>

Since this has come up, I was wondering if any DITA-aware CMS 
offerings can present the topic title or map title for selection by 
the user, instead of the file name.  This would support the use of 
GUIDs for the file names, which would guarantee uniqueness, and allow 
users to adjust titles without having to manage ditamaps, 
related-links, or xrefs.




___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

DITA file naming conventions

[Scott Prentice]

The DITA-FMx/XDocs connector presents the topic and map files with both 
filename and title in either order.

Since we're on the subject of tools and file naming options ..

DITA-FMx provides numerous ways to automate the file naming for new 
files using building blocks that can be assembled in many ways. In the 
New DITA File dialog, you enter the title of the new file, and the 
filename can be generated from that text using one of 6 title-based 
building blocks. You can also use a building block that includes a 
unique ID (which matches the ID of the new topic being created). There 
are also building blocks for topic type, date, time, and others. All of 
these can be combined as well as restricted to a specific number of 
characters, as well as being able to include folder specifications (so 
your new files end up in the right topic-based folder, if you choose to 
go that route). Details are here ..

http://docs.leximation.com/dita-fmx/1.1/?ditafmx_ref_newfileoptions.html

Personally, I prefer to use unique IDs for filenames, and only access 
the files through the map (where you see the topic titles rather than 
the filenames). This lets you keep all of the files in one folder and 
you never have to look at the file names. No matter what file naming 
convention you use (unless it's unique IDs), it breaks down and causes 
problems eventually.

Cheers,

...scott

-- 
Scott Prentice
Leximation, Inc.
www.leximation.com
+1.415.485.1892


Jim Owens wrote:
> >   As far as possible, make sure the file name matches the title of 
> the topic. So if your topic is "Inserting the Widget" then your file 
> name would be "inserting_the_widget.xml". I realize this may cause 
> problems later if the title changes, but that doesn't happen often and 
> you can usually make the change to the file name without too much 
> hassle (changing it in ditamaps, etc.).
> >
>
> Since this has come up, I was wondering if any DITA-aware CMS 
> offerings can present the topic title or map title for selection by 
> the user, instead of the file name.  This would support the use of 
> GUIDs for the file names, which would guarantee uniqueness, and allow 
> users to adjust titles without having to manage ditamaps, 
> related-links, or xrefs.
>
>

DITA file naming conventions

[Jim Owens]

 >   As far as possible, make sure the file name matches the title of 
the topic. So if your topic is "Inserting the Widget" then your file 
name would be "inserting_the_widget.xml". I realize this may cause 
problems later if the title changes, but that doesn't happen often and 
you can usually make the change to the file name without too much hassle 
(changing it in ditamaps, etc.).
 >

Since this has come up, I was wondering if any DITA-aware CMS offerings 
can present the topic title or map title for selection by the user, 
instead of the file name.  This would support the use of GUIDs for the 
file names, which would guarantee uniqueness, and allow users to adjust 
titles without having to manage ditamaps, related-links, or xrefs.

Re: [Bulk] Re: DITA file naming conventions

[Writer]

>For what it's worth, the DITA Style Guide recommends using names that match 
>the titles.

Since we are using a shared drive on my computer and no automated way to change 
file names and have the change cascade through our "system", that approach 
doesn't work for us. Partly because titles change, but also it makes it hard to 
visually identify the file you want in a list of files. Even though we didn't 
do this at first (live and learn), giving files an index type of name groups 
like files together and makes it easier to locate a file visually. Furthermore, 
even if the title changes, it is less likely that subject of the topic will.

Horse for courses, as they say.

Nadine

___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

[Bulk] Re: DITA file naming conventions

[Writer]

>For what it's worth, the DITA Style Guide recommends using names that match 
>the titles.

Since we are using a shared drive on my computer and no automated way to change 
file names and have the change cascade through our "system", that approach 
doesn't work for us. Partly because titles change, but also it makes it hard to 
visually identify the file you want in a list of files. Even though we didn't 
do this at first (live and learn), giving files an index type of name groups 
like files together and makes it easier to locate a file visually. Furthermore, 
even if the title changes, it is less likely that subject of the topic will.

Horse for courses, as they say.

Nadine

Re: DITA file naming conventions

[Roger Shuttleworth]

Hi Jim

You make a good point about updating xrefs and related-links, as well as 
ditamaps, when a file name changes.

I have made good use of the map checking function in oXygen Author. You open 
the map in Author, then run it through an automated checking routine that will 
point out any problems such as missing files or inappropriate href values.

I sent a follow-up message to the original poster correcting my recommendation 
to use folders named according to deliverables. I meant to recommend using the 
product name, not the deliverable. Different deliverables are created from a 
single pool of files, using different maps; or perhaps using the same map 
filtered by ditaval.

Thanks for your tip about GUIDs too. I will look more into that.

Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330
  _  

From: Jim Owens [mailto:jow...@magma.ca]
To: Roger Shuttleworth [mailto:rshuttlewo...@avbasesystems.com]
Cc: framers@lists.frameusers.com
Sent: Thu, 03 Nov 2011 14:04:54 -0400
Subject: Re: DITA file naming conventions

 >   As far as possible, make sure the file name matches the title of 
  the topic. So if your topic is "Inserting the Widget" then your file 
  name would be "inserting_the_widget.xml". I realize this may cause 
  problems later if the title changes, but that doesn't happen often and 
  you can usually make the change to the file name without too much hassle 
  (changing it in ditamaps, etc.).
   >
  
  Since this has come up, I was wondering if any DITA-aware CMS offerings 
  can present the topic title or map title for selection by the user, 
  instead of the file name.  This would support the use of GUIDs for the 
  file names, which would guarantee uniqueness, and allow users to adjust 
  titles without having to manage ditamaps, related-links, or xrefs.
  
  ___
  
  
  You are currently subscribed to framers as rshuttlewo...@avbasesystems.com.
  
  Send list messages to framers@lists.frameusers.com.
  
  To unsubscribe send a blank email to
  framers-unsubscr...@lists.frameusers.com
  or visit 
http://lists.frameusers.com/mailman/options/framers/rshuttleworth%40avbasesystems.com
  
  Send administrative questions to listad...@frameusers.com. Visit
  http://www.frameusers.com/ for more resources and info.
___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

RE: DITA file naming conventions

[Andy Lewis]

Hi Jim,

DITAToo from iG5 Authoring Tools can do this. Check out DITAToo at
www.ditatoo.com and some interesting discussions in the DITAToo Community
group page on LinkedIn at
http://www.linkedin.com/groups/DITAToo-Community-3964604?gid=3964604&trk=hb_
side_g.

Best wishes,
Andy Lewis



iG5 Authoring Tools
+972 54 4605708
www.ig5authoringtools.com


LinkedIn http://il.linkedin.com/in/andylewis2003
Twitter http://twitter.com/andytelaviv

-Original Message-
From: framers-boun...@lists.frameusers.com
[mailto:framers-boun...@lists.frameusers.com] On Behalf Of Jim Owens
Sent: Thursday, November 03, 2011 8:05 PM
To: Roger Shuttleworth
Cc: framers@lists.frameusers.com
Subject: Re: DITA file naming conventions

 >   As far as possible, make sure the file name matches the title of 
the topic. So if your topic is "Inserting the Widget" then your file 
name would be "inserting_the_widget.xml". I realize this may cause 
problems later if the title changes, but that doesn't happen often and 
you can usually make the change to the file name without too much hassle 
(changing it in ditamaps, etc.).
 >

Since this has come up, I was wondering if any DITA-aware CMS offerings 
can present the topic title or map title for selection by the user, 
instead of the file name.  This would support the use of GUIDs for the 
file names, which would guarantee uniqueness, and allow users to adjust 
titles without having to manage ditamaps, related-links, or xrefs.

___


You are currently subscribed to framers as andylew...@gmail.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/andylewis0%40gmail.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

Re: DITA file naming conventions

[Jim Owens]

For what it's worth, the DITA Style Guide recommends using names that 
match the titles.


 It also recommends using the extensions .dita and .ditamap, instead of 
.xml. That way, you have more control over which tool opens the file, 
and you can distinguish the files from other xml files used in DITA.


On 2011-11-03 15:02, Roger Shuttleworth wrote:

Hi Jim

You make a good point about updating xrefs and related-links, as well 
as ditamaps, when a file name changes.


I have made good use of the map checking function in oXygen Author. 
You open the map in Author, then run it through an automated checking 
routine that will point out any problems such as missing files or 
inappropriate href values.


I sent a follow-up message to the original poster correcting my 
recommendation to use folders named according to deliverables. I meant 
to recommend using the product name, not the deliverable. Different 
deliverables are created from a single pool of files, using different 
maps; or perhaps using the same map filtered by ditaval.


Thanks for your tip about GUIDs too. I will look more into that.

Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330





___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

Re: DITA file naming conventions

[Jim Owens]

>   As far as possible, make sure the file name matches the title of 
the topic. So if your topic is "Inserting the Widget" then your file 
name would be "inserting_the_widget.xml". I realize this may cause 
problems later if the title changes, but that doesn't happen often and 
you can usually make the change to the file name without too much hassle 
(changing it in ditamaps, etc.).

>

Since this has come up, I was wondering if any DITA-aware CMS offerings 
can present the topic title or map title for selection by the user, 
instead of the file name.  This would support the use of GUIDs for the 
file names, which would guarantee uniqueness, and allow users to adjust 
titles without having to manage ditamaps, related-links, or xrefs.


___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

Re: DITA file naming conventions

[Roger Shuttleworth]

Hello hessiansx4

Join the dita-users group on Yahoo and search in the archives there. You'll 
find lots of good advice from people who know a heck of a lot more about XML 
than I do. But I can tell you what I have gleaned from various user groups:


* Use only lower-case lettering for both files and folders. Why? XML is 
case-sensitive, so you don't want authors to stumble over which case to use for 
href attribute values, for example. It's the KISS principle.
* Remember also that, since XML is all about interchangeability, and your 
content may end up in a Linux or Unix environment, you should avoid all special 
characters except for underscores in file and folder names. That includes 
periods and spaces: ban them in folder and file names.
* As far as possible, make sure the file name matches the title of the topic. 
So if your topic is "Inserting the Widget" then your file name would be 
"inserting_the_widget.xml". I realize this may cause problems later if the 
title changes, but that doesn't happen often and you can usually make the 
change to the file name without too much hassle (changing it in ditamaps, etc.).
* As you can see above, use underscores in file names instead of spaces. 
CamelCase is not a good idea, for reasons given above.

* We add a suffix to the file name to indicate the topic type: 
inserting_the_widget_c.xml is a concept; _t for a task; _r for a reference; _tp 
for a topic (rarely used). That makes it easier to locate the file in a 
concepts folder, for example.
* If you use XML and DITA, you will find yourself working with large numbers of 
topic files. This may sound intimidating, but with good folder structure it is 
not a problem.
* For ditamaps, make full use of the nesting capabilities (that is, a map 
referencing a map) so that your maps don't get too large. It is easier to 
handle a map that has five sub-maps than to handle one map containing hundreds 
of topics.

* Don't assume that these rules are irrelevant if you're not planning on using 
XML right now. There's great benefit in using structured authoring and DITA 
even without going so far as to use XML, but you probably will want to take 
that step in the future. Don't paint yourself into a corner.
As regards folder structure, opinions vary. Most people   recommend keeping 
ditamaps in a maps folder, and topics in three or four   sibling folders 
(concepts, topics, reference, tasks). Some people just   have a topics folder 
and keep all topic types together; that may work if your numbers are relatively 
small. It is good   practice to keep relative paths simple (for example, for 
href attributes). So organize your folders in a shallow structure; something 
like:
 deliverable_name
maps
concepts
images
reference
tasks
topics
  
  Or:
 deliverable_name
images
  maps
  concepts
  reference
  tasks
  topics
  
  That way, your relative paths from map to topic are simple, and from topic to 
image. What you don't want are long ../../../../ strings in the hrefs. Since 
you will be using FM, your maps folder will eventually contain other things 
apart from maps.

One last thing: Take a look at DITA-FMx from leximation.com. It simplifies 
things a lot. If you're making the switch in the near future, don't buy 
DITA-FMx until the new version comes out in a few months.

In our experience, you can manage many hundreds of files without needing an 
expensive content management system. Get used to working with XML first before 
even thinking about a CMS.

Hope this helps.
Roger


Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330
  _  

From: hessiansx4 [mailto:hessian...@yahoo.com]
To: framers@lists.frameusers.com [mailto:framers@lists.frameusers.com]
Sent: Thu, 03 Nov 2011 02:49:05 -0400
Subject: DITA file naming conventions



Hello All! My company is in the process of transitioning from FM8 unstructured 
> FM10 DITA and are discussing file naming conventions. Have any of you had a 
similar experience (transitioning to DITA)? Any caveats you want to share about 
the process (what worked/what didn't)? How about file naming conventions? Any 
and all suggestions are welcomed!  ___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

DITA file naming conventions

[Roger Shuttleworth]

Hello hessiansx4

Join the dita-users group on Yahoo and search in the archives there. You'll 
find lots of good advice from people who know a heck of a lot more about XML 
than I do. But I can tell you what I have gleaned from various user groups:


* Use only lower-case lettering for both files and folders. Why? XML is 
case-sensitive, so you don't want authors to stumble over which case to use for 
href attribute values, for example. It's the KISS principle.
* Remember also that, since XML is all about interchangeability, and your 
content may end up in a Linux or Unix environment, you should avoid all special 
characters except for underscores in file and folder names. That includes 
periods and spaces: ban them in folder and file names.
* As far as possible, make sure the file name matches the title of the topic. 
So if your topic is "Inserting the Widget" then your file name would be 
"inserting_the_widget.xml". I realize this may cause problems later if the 
title changes, but that doesn't happen often and you can usually make the 
change to the file name without too much hassle (changing it in ditamaps, etc.).
* As you can see above, use underscores in file names instead of spaces. 
CamelCase is not a good idea, for reasons given above.

* We add a suffix to the file name to indicate the topic type: 
inserting_the_widget_c.xml is a concept; _t for a task; _r for a reference; _tp 
for a topic (rarely used). That makes it easier to locate the file in a 
concepts folder, for example.
* If you use XML and DITA, you will find yourself working with large numbers of 
topic files. This may sound intimidating, but with good folder structure it is 
not a problem.
* For ditamaps, make full use of the nesting capabilities (that is, a map 
referencing a map) so that your maps don't get too large. It is easier to 
handle a map that has five sub-maps than to handle one map containing hundreds 
of topics.

* Don't assume that these rules are irrelevant if you're not planning on using 
XML right now. There's great benefit in using structured authoring and DITA 
even without going so far as to use XML, but you probably will want to take 
that step in the future. Don't paint yourself into a corner.
As regards folder structure, opinions vary. Most people   recommend keeping 
ditamaps in a maps folder, and topics in three or four   sibling folders 
(concepts, topics, reference, tasks). Some people just   have a topics folder 
and keep all topic types together; that may work if your numbers are relatively 
small. It is good   practice to keep relative paths simple (for example, for 
href attributes). So organize your folders in a shallow structure; something 
like:
 deliverable_name
maps
concepts
images
reference
tasks
topics

  Or:
 deliverable_name
images
  maps
  concepts
  reference
  tasks
  topics

  That way, your relative paths from map to topic are simple, and from topic to 
image. What you don't want are long ../../../../ strings in the hrefs. Since 
you will be using FM, your maps folder will eventually contain other things 
apart from maps.

One last thing: Take a look at DITA-FMx from leximation.com. It simplifies 
things a lot. If you're making the switch in the near future, don't buy 
DITA-FMx until the new version comes out in a few months.

In our experience, you can manage many hundreds of files without needing an 
expensive content management system. Get used to working with XML first before 
even thinking about a CMS.

Hope this helps.
Roger


Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330
  _  

From: hessiansx4 [mailto:hessian...@yahoo.com]
To: framers at lists.frameusers.com [mailto:framers at lists.frameusers.com]
Sent: Thu, 03 Nov 2011 02:49:05 -0400
Subject: DITA file naming conventions



Hello All! My company is in the process of transitioning from FM8 unstructured 
> FM10 DITA and are discussing file naming conventions. Have any of you had a 
similar experience (transitioning to DITA)? Any caveats you want to share about 
the process (what worked/what didn't)? How about file naming conventions? Any 
and all suggestions are welcomed!  
-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/c4036f3a/attachment.html>

AW: I can PDF individual files in book, but NOT the whole book

[Georg Eck]

Hi Clara,



please check following way:

1.   Is your FrameMaker 10.0.1.402 or 408?
If no, then update your FM with last patch

2.   Open the whole book (CTRL-File > Open all file in book).
if a book message appear or FM crash: Then 

a.   Open the book

b.  Select Menu Edit > Disable Reference Update 

c.   Then Open all files in a book.

d.  Select Menu Edit > Book Update

e.  Then Save as PDF ...



What is the result?



-  Georg
(Adobe Certified Expert FrameMaker) 

-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/411c5ba1/attachment.html>

Re: DITA file naming conventions

[Yves Barbion]

Hi hessiansx4

Some more tips:

   - Avoid spaces and special characters in file names, also in file names
   of graphics
   - Buy some tools and Framescripts to convert your unstructured Fm files
   to DITA: MIF2Go and some Framescripts to rename your topics and change the
   topicrefs in the ditamap accordingly
   - Buy DITA-FMx for enhanced DITA support in FrameMaker 10: you will be
   able to generate a PDF-ready FrameMaker book from your bookmap. The cover,
   frontmatter, table of contents, index and other generated lists will be
   added automatically in 1 go.
   - Get training and coaching. We can help you with the whole process.
   Feel free to contact me off-list if you're interested.


> Kind regards


-- 
Yves Barbion
www.scripto.nu
___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

Re: DITA file naming conventions

[Writer]

Hessiansx4, you might also want to look at this forum: 
http://tech.groups.yahoo.com/group/framemaker-dita/messages

As for naming conventions, we name our files with a letter based on the 
topic type, all lower case, only underscores to separate "words", and 
use a "phrase" that is like an index term according to the content of 
the topic, not what manual it goes in. For example:

concept: c_widgets_description_american, c_widgets_description_canadian

reference: r_widgets_parameters
task: t_widgets_parameters_setting
glossary: g_widgets, g_thingmabobs

conref: cr_widget_daily_statistics (that might be a conref for a report 
name...we also use conrefs for product names)
map: m_productname_users_guide_print

We name ditaval files the same as the corresponding map file and store 
them in the same folder with the maps. For example, 
m_productname_users_guide_print.ditaval.


We don't use a CMS, so my (small) team shares a folder on my computer. In it we 
have subfolders to store different topic types:

concepts
conrefs
glossary

graphics
maps

references
tasks


It's difficult to answer your open-ended questions just off the top of my 
head at the moment (it's still morning here); however, other points you 
might want to examine and plan out ahead of your transition are:

o What kind of output do you need?
o Are you using a CMS? If not, how will you manage/share your DITA files?
o If you are using a CMS, does your CMS provide processors to create those 
outputs or do you need plug-ins?
o Do you have developer resources, or are you very technically inclined?
o What is your budget like?
o Do you have support from above?
o How large is your tech writing department?
o How much R&D time do you have to develop your projects (including setting up 
your tools to create your required output)?
o Will you have to create content/product while you are converting to DITA?
o Do you need to support other source format besides DITA?
o How complex will your DITA be, and do your tools support DITA 1.2 or only 1.1?

I can recommend the following software:

WebWorks ePublisher: Handles DITA beautifully, and if you need to create output 
while you're transitioning, you can mix DITA, FM (unstructured), and 
Word providing you have bought all three adapters (www.webworks.com).

Suite Solutions' Ditaval File Generation Utility and DITA Packager Utility: 
free, but invaluable 
(http://www.suite-sol.com/pages/resources/downloads.html)
Mif2Go or Dita2Go: for conversion from unstructured to structured. We also use 
Mif2Go to convert FM files to Word for developers and customers.


If you have specific questions, I'd be happy (to try) to answer them for you 
off forum, too.

Hope you find something helpful in that,

Nadine



>
>From: hessiansx4 
>To: "framers@lists.frameusers.com" 
>Sent: Thursday, November 3, 2011 2:49:05 AM
>Subject: DITA file naming conventions
>
>
>Hello All! My company is in the process of transitioning from FM8 
>unstructured > FM10 DITA and are discussing file naming conventions. Have any 
>of you had a similar experience (transitioning to DITA)? Any caveats you want 
>to share about the process (what worked/what didn't)? How about file naming 
>conventions? Any and all suggestions are welcomed!
>___
>
>
>You are currently subscribed to framers as generic...@yahoo.ca.
>
>Send list messages to framers@lists.frameusers.com.
>
>To unsubscribe send a blank email to
>framers-unsubscr...@lists.frameusers.com
>or visit 
>http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca
>
>Send administrative questions to listad...@frameusers.com. Visit
>http://www.frameusers.com/ for more resources and info.
>
>
>___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

DITA file naming conventions

[Writer]

Hessiansx4, you might also want to look at this forum: 
http://tech.groups.yahoo.com/group/framemaker-dita/messages

As for naming conventions, we name our files with a letter based on the 
topic type, all lower case, only underscores to separate "words", and 
use a "phrase" that is like an index term according to the content of 
the topic, not what manual it goes in. For example:

concept: c_widgets_description_american, c_widgets_description_canadian

reference: r_widgets_parameters
task: t_widgets_parameters_setting
glossary: g_widgets, g_thingmabobs

conref: cr_widget_daily_statistics (that might be a conref for a report 
name...we also use conrefs for product names)
map: m_productname_users_guide_print

We name ditaval files the same as the corresponding map file and store 
them in the same folder with the maps. For example, 
m_productname_users_guide_print.ditaval.


We don't use a CMS, so my (small) team shares a folder on my computer. In it we 
have subfolders to store different topic types:

concepts
conrefs
glossary

graphics
maps

references
tasks


It's difficult to answer your open-ended questions just off the top of my 
head at the moment (it's still morning here); however, other points you 
might want to examine and plan out ahead of your transition are:

o What kind of output do you need?
o Are you using a CMS? If not, how will you manage/share your DITA files?
o If you are using a CMS, does your CMS provide processors to create those 
outputs or do you need plug-ins?
o Do you have developer resources, or are you very technically inclined?
o What is your budget like?
o Do you have support from above?
o How large is your tech writing department?
o How much R&D time do you have to develop your projects (including setting up 
your tools to create your required output)?
o Will you have to create content/product while you are converting to DITA?
o Do you need to support other source format besides DITA?
o How complex will your DITA be, and do your tools support DITA 1.2 or only 1.1?

I can recommend the following software:

WebWorks ePublisher: Handles DITA beautifully, and if you need to create output 
while you're transitioning, you can mix DITA, FM (unstructured), and 
Word providing you have bought all three adapters (www.webworks.com).

Suite Solutions' Ditaval File Generation Utility and DITA Packager Utility: 
free, but invaluable 
(http://www.suite-sol.com/pages/resources/downloads.html)
Mif2Go or Dita2Go: for conversion from unstructured to structured. We also use 
Mif2Go to convert FM files to Word for developers and customers.


If you have specific questions, I'd be happy (to try) to answer them for you 
off forum, too.

Hope you find something helpful in that,

Nadine



>
>From: hessiansx4 
>To: "framers at lists.frameusers.com" 
>Sent: Thursday, November 3, 2011 2:49:05 AM
>Subject: DITA file naming conventions
>
>
>Hello All! My company is in the process of transitioning from FM8 
>unstructured?> FM10 DITA and are discussing file naming conventions. Have any 
>of you had a similar experience (transitioning to DITA)? Any caveats you want 
>to share about the process (what worked/what didn't)? How about file naming 
>conventions? Any and all suggestions are welcomed!
>___
>
>
>You are currently subscribed to framers as generic668 at yahoo.ca.
>
>Send list messages to framers at lists.frameusers.com.
>
>To unsubscribe send a blank email to
>framers-unsubscribe at lists.frameusers.com
>or visit 
>http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca
>
>Send administrative questions to listadmin at frameusers.com. Visit
>http://www.frameusers.com/ for more resources and info.
>
>
>
-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/e36eafe5/attachment.html>

DITA file naming conventions

[hessiansx4]

Hello All! My company is in the process of transitioning from FM8 
unstructured > FM10 DITA and are discussing file naming conventions. Have any 
of you had a similar experience (transitioning to DITA)? Any caveats you want 
to share about the process (what worked/what didn't)? How about file naming 
conventions? Any and all suggestions are welcomed!___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

Updating from 7.2 to 10

[Lebbink, Belinda]

Hello all.

What kind of problems can I expect when I update my Framemaker from v7.2 (xp) 
to v10 on w7?

I use structured FM with R/W-rules, templates, edd & xml.


Met vriendelijke groet,
Sdu Uitgevers

Belinda Lebbink
Coördinator productrealisatie Kosteninformatie

p/a Hanzestraat 1 Doetinchem
Postbus 20025
2500 BC  Den Haag
(0314) 349 668
b.lebb...@sdu.nl

Voor meer informatie over onze producten: www.sdu.nl en 
www.kosteninformatie.nl

___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.

Updating from 7.2 to 10

[Lebbink, Belinda]

Hello all.

What kind of problems can I expect when I update my Framemaker from v7.2 (xp) 
to v10 on w7?

I use structured FM with R/W-rules, templates, edd & xml.


Met vriendelijke groet,
Sdu Uitgevers

Belinda Lebbink
Co?rdinator productrealisatie Kosteninformatie

p/a Hanzestraat 1 Doetinchem
Postbus 20025
2500 BC  Den Haag
(0314) 349 668
b.lebbink at sdu.nl<mailto:b.lebbink at sdu.nl>

Voor meer informatie over onze producten: www.sdu.nl<http://www.sdu.nl/> en 
www.kosteninformatie.nl<http://www.kosteninformatie.nl/>

-- next part --
An HTML attachment was scrubbed...
URL: 
<http://lists.frameusers.com/pipermail/framers/attachments/2003/f4e46d0b/attachment.html>

AW: I can PDF individual files in book, but NOT the whole book

[Georg Eck]

Hi Clara,

 

please check following way:

1.   Is your FrameMaker 10.0.1.402 or 408?
If no, then update your FM with last patch

2.   Open the whole book (CTRL-File > Open all file in book).
if a book message appear or FM crash: Then 

a.   Open the book

b.  Select Menu Edit > Disable Reference Update 

c.   Then Open all files in a book.

d.  Select Menu Edit > Book Update

e.  Then Save as PDF ...

 

What is the result?

 

-  Georg
(Adobe Certified Expert FrameMaker) 

___


You are currently subscribed to framers as arch...@mail-archive.com.

Send list messages to framers@lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit 
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com

Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.