Re: Reuse - best practices #reuse


Ron Wheeler
 

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:

Products
    /Build
        Common Topics
        How to Build AA
        How to Build BB
    /Fix
        Common Topics
        How to Fix AA
        How to Fix BB
    /Specs
        Common Topics
        AA
        BB
    /Health&Safety
        Common Topics
            English
            French
        AA
            English
            French
        BB
            English
            French
    /Marketing
        Common Topics
            English
            French
        AA
            English
            French
        BB

            English
            French

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 maintained.

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.

Ron


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:

Pub-Model-AA/
topics/            How do Build Something-AA
           How to Fix Something-AA
media/
or

Pub-Model-AA/
topics/            How do Build Something
           How to Fix Something
media/

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 model-BB.
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?

 

Join main@dita-users.groups.io to automatically receive all group messages.