toggle quoted messageShow quoted text
With naming scheme one, are you not going to be more puzzled when
you reuse "How to Build Something-AA" in "Pub-Model-BB"?
Another alternative might be:
How to Build AA
How to Build BB
How to Fix AA
How to Fix BB
This might work well if you have different teams (Manufacturing,
Customer Service, Product Engineering, Product Safety, Marketing,
etc.) responsible for maintaining the documentation.
I am not sure that there is only 1 right answer but you might
find it helpful to hypothesize several reuse scenarios to see how
easy it is to determine the hierarchy of a topic when you might
have it in several documents.
I would be tempted to use mindmapping to explore potential
structures and to think about how the documentation will be
On the good side of DITA, if you use keyrefs to tie
topic names(keys) to file URIs, you can change your mind later and
have only 1 map to alter if you change the physical organization
of the topic files.
With keys, you can afford to be wrong as long as it
works and fix it easily as soon as it does not work.
On 2020-03-02 7:41 p.m., Matt Lorenzi
via Groups.Io wrote:
One other reuse issue I have has to do with file naming. I
struggle with naming conventions and how detailed I should be
with file names. I will start with Pub-Model-AA.
These are the two ways I would think you could name the
files, see below:
How do Build Something-AA
How to Fix Something-AA
How do Build
How to Fix Something
Which method is least likely to cause confusion? If I go with
the first method I will always know the task: How do Build Something-AA belongs
to model-AA, even I reuse and reference How do Build Something-AA in
But if I use just use: How do Build Something, I
can still use it across multiple documents, I just won't know
immediately where it belongs. It was suggested to go with this
latter method as the parent folder will identify the model.
On the other hand, I've also read one should make the file name
as specific as possible, but am I taking this too literally by
including the model name in each file name?