Topics

Reuse - best practices #reuse

Matt Lorenzi
 

I know this thread is a can of worms, but here we go anyway. How does one best organize content for maximum content reuse?

I know ideally you would do some serious information architecture to strategize where to put everything. But in some cases you inherit a folder structure and it's too far along to backtrack.

Is there a resource for a high-level overview of folder/file structure for content reuse?

I want to try and avoid referencing topics from Document A into Document B, C, D, etc....then topics from Document B into Document A, C, D. You see where I am going with this. 
Is it best to put all imaginable common content into COMMON folder and go from there? OR, should I not even worry about it and leave it up to the ditamap? Ditamap does not care where the files reside, but as a content author you want to know where the most commonly used topics reside. 

My next question would be on profiling and how to best address that, but let's stick to folder structure for now.

ekimber@contrext.com
 

I agree that avoiding having topics specific to publication A directly reuse topics specific to (or organized as part of) publication B is a bad idea, just as doing conrefs to content in topics that are not explicitly warehouse topics is a good idea.

For that reason I'm partial to the common folder approach.

Beyond that I find that having one folder per organizing structure (i.e., part, chapter, etc.) works well. With that structure it then makes sense to have a map per directory.

That establishes a pattern where each directory in your document structure is represented by a map and the resources specific to that structure. Depending on the volume of data I find it then makes sense to have subdirectories for topics, media, etc., so that your structure starts to look like:

Pub-01.ditamap
Pub-01/
Chapter-01/
Chapter-01.ditamap
topics/
media/
Chapter-02/
Chapter-02.ditamap
topics/
media/
common/
...

Within a common directory it usually makes sense to organize either by topic type (concepts, reference, tasks, etc.) or by subject area, basically, what will be most general and make most sense to users trying to find things.

Note that in the structure above the root maps for each publication are above the directories for each publication's content, in order to avoid issues with having references from root maps to files that are not directly beneath the map in the file system.

Cheers,

Eliot
--
Eliot Kimber
http://contrext.com


On 2/28/20, 4:13 PM, "Matt Lorenzi via Groups.Io" <main@dita-users.groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:

I know this thread is a can of worms, but here we go anyway. How does one best organize content for maximum content reuse?

I know ideally you would do some serious information architecture to strategize where to put everything. But in some cases you inherit a folder structure and it's too far along to backtrack.

Is there a resource for a high-level overview of folder/file structure for content reuse?

I want to try and avoid referencing topics from Document A into Document B, C, D, etc....then topics from Document B into Document A, C, D. You see where I am going with this.
Is it best to put all imaginable common content into COMMON folder and go from there? OR, should I not even worry about it and leave it up to the ditamap? Ditamap does not care where the files reside, but as a content author you want to know where the most commonly used topics reside.

My next question would be on profiling and how to best address that, but let's stick to folder structure for now.

Matt Lorenzi
 

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?

 

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?

 

Matt Lorenzi
 

This is great advice. I am still only starting to get my feet wet with keyrefs. Playing around with using them for product names and other variables - not so much fore referencing topics - but I can see the power behind doing so.

Matt Lorenzi
 

I think one of the biggest concerns I have is losing track of the original "home" of a topic. It isn't always known ahead of time which topics maybe become common to other models; it might not even be known at the time that other models are coming along. So I am sure in practice you simply do a topicref to the topic needed - wherever it may be. I sense this is where the power of keyrefs come in. I need more coffee to wrap my head around this.

ekimber@contrext.com
 

Yes, one of the values of keyrefs is that it creates a level of indirection between the initial reference to something (a conref, an xref, a topicref from a map) and the thing itself.

This indirection enables several important things:

1. Keeps the references separate from the details of where the referenced thing is at any given time. This lets you move the target thing around, rename it, etc., without breaking all the links to it. When the details of the thing change you only have to update the key definition(s) that point to it. This value of key references is independent of any re-use you might do not do. It simply makes your content much less fragile in general.

2. Allows the same reference to resolve to *different* things in different use contexts. This is essential when you are doing reuse so that the same topic (or re-used map) can have links that point to a single, invariant, key name where the key name may resolve to different targets in the context of different maps. And here by "target" I mean both things that you point to (topics, images, external resources like web sites) and text values (i.e., keys used to create "variable" text).

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 3/3/20, 12:16 PM, "Matt Lorenzi via Groups.Io" <main@dita-users.groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:

I think one of the biggest concerns I have is losing track of the original "home" of a topic. It isn't always known ahead of time which topics maybe become common to other models; it might not even be known at the time that other models are coming along. So I am sure in practice you simply do a topicref to the topic needed - wherever it may be. I sense this is where the power of keyrefs come in. I need more coffee to wrap my head around this.

Patricia Billard
 

Hi Matt, A topicref to a topic "wherever that may be" is not great specifically because you do lose track of what topics are reused in some other map, and you don't always end up with one "golden topic" source.  A best practice is to always put reused/reusable content in a specific place in your CMS structure.  For example, a folder called "Common Content" or "Shared Content" or something like that.  For the situation in which you start out with something you don't think would be shared, and now someone wants to reuse it, you'd need a business process to move that topic in to a Common Content folder at that time.

Elizabeth Gschwind (FICO)
 

I agree Patricia. We put our shared content in folders labelled “Common” in our CMS, and also add the word “COMMON” to the file names so those objects are easy to identify.

 

This email and any files transmitted with it are confidential, proprietary and intended solely for the individual or entity to whom they are addressed. If you have received this email in error please delete it immediately.

Ron Wheeler
 

You are on the right track.
keyrefs, topicrefs and their cousins make it easy to reposition the physical location of things without disturbing your main map.
If you define these in a separate file which you reference in your main map at the start, such as I have done

    <topicref href="description_variables.ditamap"
        format="ditamap" processing-role="resource-only" />

you will be able to restructure your physical locations and have all DITA projects that use the keys be automatically "fixed".
"resource-only" is the key that keeps your map of keys from being included as content.
The name "description_variables.ditamap" is arbitrary and only gets its name from the fact that the project is all about condo descriptions for our condo association.
(I needed to produce  master descriptions of all condos as well as a description of each condo as a separate document,  in 2 languages.)

Any other project that needs to reuse any of the content, simply has to include this reference and their project will find all of the files in their current locations regardless of any physical restructuring that has occurred.

Very helpful even where sharing is not contemplated. I restructured my files several times as I developed the DITA application and it was easy to reorganize things without having to go through all of the maps to re-specify links.

Ron


On 2020-03-03 1:16 p.m., Matt Lorenzi via Groups.Io wrote:
I think one of the biggest concerns I have is losing track of the original "home" of a topic. It isn't always known ahead of time which topics maybe become common to other models; it might not even be known at the time that other models are coming along. So I am sure in practice you simply do a topicref to the topic needed - wherever it may be. I sense this is where the power of keyrefs come in. I need more coffee to wrap my head around this.

Matt Lorenzi
 

This is such good information. Thanks to everyone for offering their suggestions.