Best practice for organizing topics in folders

[fchan]

I know folders are for organizing similar topics so that it's easy for the writer to spot missing information. But I don't know if there are implications in terms of how easy to generate the TOC, to import styles, to build multiple outputs, etc.

For example, I can have folders like this:
Main course folder
--Meat dish (topic)
--Vegetable dish (topic)
Dessert folder
--Cakes (topic)
--Cookies (topic)

Or I can have only one folder containing all four topics.

Or two folders such as:
Kids party folder
--Meat dish (topic)
--Cookies (topic)
--Cakes (topic)
Grownups party folder
--Vegetable dish (topic)

These are just examples. In reality, the project contains many more topics. If I'm sure that I have no problem making sure that all topics are in my project, is it OK to have 100 topics in one folder?

[LTinker68]

I don't think there are any limits to how many files can be in a folder, unless Windows has a limit. However, it will be easier for you in some cases to apply conditional tags at the folder level instead of at the topic level. If you have 100 files in a folder then you can't apply a conditional tag to the folder unless you want all 100 files to be affected by the same conditional tag. If you don't, then you have to modify all the files individually (although you can speed up that process using the split pane option).

The other main reason you probably won't want 100 files in a folder is that means you have more scrolling to do in the Context Editor when you want to get to a file to edit it.

I tend to organize my folders similarly to the "books" I use in the TOC. That's not a requirement -- it just seems to help me if my folder structure mimics how the content is cataloged for the end user. Although I'll have a few extra folders that they won't see, usually for print-specific content like the title page, copyright page, etc.

[RamonS]

When you follow the DITA idea then you have three top level folders:
- Task
- Concept
- Reference
Connections between topics are created via links. For example, a Concept topic links to several Task topics and maybe some Reference topics, a Task topic links to a few Concept topics (because the task is used in multiple concepts) and links to a few Reference topics. Theoretically, you could have Reference topics link to Tasks and Concepts, but I wonder how many users would use a Reference as entry point, but they might be looking for a single entity and knowing where it is used and how it can be modified might help.
Under each of these main folders you can have subfolders. For Tasks having a logical sort might make most sense, for References it is probably alphabetical, and for Concepts again a logical order, from top level concepts to very low level ones, but might also follow a logical progression through the application and thus have the same order as Tasks. With that and with writing topics so that they fit into one of these categories you end up with each topic showing up only once in the ToC. The need to have a topic appear multiple times is satisfied by linking topics to each other.

Aside from all that, there is no limit on how often a topic is linked in the ToC. If you want to use autosync then you have to either add each topic only once or create a snippet and plop that into topics that contain nothing else than that snippet. Editing the snippet will change the content everywhere and after compile each topic is 'unique', at least as far as ToC and autosync is concerned.

[NorthEast]

There are no particular implications/advantages with regards to building your TOC or using imports.

I find folders useful for conditions; you can apply a condition tag to a folder, and use that to exclude all the files within that folder (so you don't need to apply condition tags to individual files).

Also, if you use External Resources, you can synchronise folders from other projects or locations.

[kwag_myers]

I ran into this dilemma working for a client with a three-click rule (no more than three levels in the TOC). I'm not sure you can have a standard for this, but my strategy for large projects is to find a balance between too few and too many folder levels. Somewhere between four and six seem to be adequate for most of the projects I've worked on.

To continue with the DITA methodology, I like to use the Concept topic in the TOC with Reference and Tasks as sub-topics so I leave them out of the TOC if I need to. However, I'm starting to get away from DITA, since I've found that I can really pack a lot of information into one topic with expanding text.

[Mad_Hatter]

In the Content Explorer, I leave all my topics listed alphabetically under the Content folder (and there are MANY). I condition for Print and Web either inside the topic or in the TOC, but I also use some visual conditions in the Content Explorer. I'll apply an 'In Progress' condition (in Content Explorer) to topics that are being worked on. I don't move them to the TOC until they're finished and ready to be published. I remove the visual indicator at that time. You may ask "How do you find your topics if they're not organized in folders?". I'm glad you asked! I use the TOC to access topics for maintenance. For new topics that aren't yet in the TOC, that's where my visual indicator conditions come in. I use three (Black, Red, and Blue) and I just scroll down until I see which one I'm looking for.

I look at the Content Explorer as sort of a staging area where I get my topics ready. When they're good, I move them over to the TOC for publishing. I have multiple TOCs and this works great for me.

[i-tietz]

In the Content Explorer, I leave all my topics listed alphabetically under the Content folder (and there are MANY). I condition for Print and Web either inside the topic or in the TOC, but I also use some visual conditions in the Content Explorer. I'll apply an 'In Progress' condition (in Content Explorer) to topics that are being worked on. I don't move them to the TOC until they're finished and ready to be published. I remove the visual indicator at that time. You may ask "How do you find your topics if they're not organized in folders?". I'm glad you asked! I use the TOC to access topics for maintenance. For new topics that aren't yet in the TOC, that's where my visual indicator conditions come in. I use three (Black, Red, and Blue) and I just scroll down until I see which one I'm looking for.

I look at the Content Explorer as sort of a staging area where I get my topics ready. When they're good, I move them over to the TOC for publishing. I have multiple TOCs and this works great for me.

This only works, if you have ALL your topics in the TOC ... that's your concept, right?
We have CSH topics and popup topics in our help that we don't add to the TOC.
Thinking about having a TOC with about 3.000 items (biggest project we currently have) ... the TOC wouldn't be helpful anymore - not really ...

[kevinmcl]

In the Content Explorer, I leave all my topics listed alphabetically under the Content folder (and there are MANY). I condition for Print and Web either inside the topic or in the TOC, but I also use some visual conditions in the Content Explorer. I'll apply an 'In Progress' condition (in Content Explorer) to topics that are being worked on. I don't move them to the TOC until they're finished and ready to be published. I remove the visual indicator at that time. You may ask "How do you find your topics if they're not organized in folders?". I'm glad you asked! I use the TOC to access topics for maintenance. For new topics that aren't yet in the TOC, that's where my visual indicator conditions come in. I use three (Black, Red, and Blue) and I just scroll down until I see which one I'm looking for.

I look at the Content Explorer as sort of a staging area where I get my topics ready. When they're good, I move them over to the TOC for publishing. I have multiple TOCs and this works great for me.

I have sizable ToCs, nested to several levels, but usually only a couple of ToCs per project.

When I'm looking at a file in Content Explorer, it sometimes becomes important to FIND that file in the ToC. This is especially important if the same file is referenced in two or more places in the ToC.
If I use the "Locate in ToC" action from the right-click menu, it obligingly shows me that my topic exists in my Primary ToC and my Print-only ToC.... wow... how [NOT] useful.
It can take minutes and minutes to scan through a big ToC. The same topic might be identified differently in different folders of the ToC, because of the surrounding content, so that's a LOT of hovering and waiting for hovertext to appear.

Is there a more direct, less time-consuming way?
The obvious thing would be for the "Locate in ToC" function to HIGHLIGHT every occurrence of the selected topic in the currently-open ToC. Well, obvious to me, perhaps other folks would think that silly and unhelpful. But how do you normally find an item in a ToC, when you don't recall what you labeled it last year?

I had this just last week. I had one topic that was linked in three widely separated places in my primary ToC, once with the concepts, once for admin & maintenance, and once again in a troubleshooting section. In each different section of the ToC, that topic had a different name/label appropriate to where it was being called, and none of them was a match for the actual filename. Took me a while to find all three... or at least, the three that I know about... the point in finding them was to adjust the ToC entries to make them easier to recognize, in light of feedback from the field.

This is only going to get worse, now that there's a second techwriter in our office.

What do others do?

[NorthEast]

What do others do?

I don't have duplicate links to the same topic in the TOC; as doing so means that TOC synchronisation and breadcrumbs don't work.

MadCap's own Webhelp does this, and it's annoying because you can select a topic in the TOC, and find the TOC highlight moves to a topic in an entirely different section in the TOC (where the topic link is duplicated).

If I need to duplicate the content from a topic, I create a separate topic file for each instance, and include the shared content in a snippet. So the snippet could be the entire topic content, or maybe just everything apart from the main heading.

This method also allows you to have variations in each copy of the topic/snippet by using snippet conditions.


As for the Locate in TOC feature; I'd report that as a bug to MadCap, as it should find all TOC links, not just one TOC link in one file.

[kevinmcl]

Ooooo! Excellent.

I hadn't thought of doing it that way.
Is that a recommended approach in one of the Flare docs I haven't read?
Or is it just what the smart people have figured out?

Either way, very smart, and I'm going to start doing it that way immediately. Thanks.
I hadn't clued-in to the breadcrumbs issue. Explains some things...

It will also improve things for single-sourcing to print, in addition to the WebHelp.


Um, snippets. Is it just me, or does the snippet selection dialog seem to display the available snippet files in a rather arbitrary order? I don't normally find them presented in alphabetical order when I'm looking to edit or insert one.

[NorthEast]

It's not a recommended approach by MadCap, as their own help has problems!

It's been mentioned a few times in the forum though; it's a good way to handle duplicate topics in the TOC, without breaking the TOC synchronisation and breadcrumbs.

I think it lists snippet in order by Path (folder) first, then by File name. Just click File to re-order by name.