Folder Structure Best Practices

Mirror the physical plant#

The structure that ages best follows the equipment:

Riverside Plant
+-- Utilities
|   +-- Boiler House
|   |   +-- Boiler 1
|   |   +-- Boiler 2
|   |   +-- Boiler 3
|   +-- Compressed Air
|   +-- Water Treatment
+-- Production
|   +-- Line 1
|   |   +-- Filler
|   |   +-- Capper
|   |   +-- Labeller
|   +-- Line 2
+-- Quality
    +-- Laboratory

Anyone who knows the plant can find anything in this tree without being taught it. That is the whole test.

What not to mirror#

Not the historian's tag naming. PLANT1_L2_FLW encodes control system topology and instrument numbering. Nobody thinks in it, and it will not survive the next PLC upgrade.

Not the org chart. Reporting lines change every couple of years; the boiler house does not move. Model the plant and let reports slice by responsibility.

Not the dashboards. A folder called Management Dashboard Measures is a structure built around one deliverable. The second deliverable will not fit, and the measures will be in the wrong place forever.

Not the project phases. Phase 1, Phase 2 are meaningful for six months and confusing for a decade.

Consistency beats cleverness#

Parallel things should look parallel. If Line 1 has Filler, Capper, Labeller, then Line 2 should too, in the same order, with the same names — even if Line 2's labeller is a different make.

This matters more than it sounds:

• Templates need it. A template instantiated into inconsistent structures produces inconsistent instances.
• Model attributes need it. Attributes are inherited by position in the tree.
• Comparison needs it. Charts and reports that compare lines rely on finding equivalent measures in equivalent places.
• Handover needs it. The next person infers the pattern from one example and applies it correctly.

Naming#

Use the names people say. Boiler 1, not BLR-001. If operators call it the Big Mixer, Big Mixer is a better folder name than Mixer 3.

Zero-pad only when you will exceed nine. Line 1…Line 9 sorts correctly. If there will be more than nine, use Line 01 from the start, because renaming later means updating every reference someone has written down.

Be consistent about singular and plural. Container folders plural (Boilers), specific equipment singular (Boiler 1). Pick a rule and hold it.

Avoid redundant prefixes. Inside Boiler House, a folder called Boiler House Boiler 1 is noise. The path already says it.

Avoid abbreviations that need a glossary. Water Treatment costs nothing over WTP and needs no explanation.

Avoid characters that travel badly. Slashes, colons, quotes, and other punctuation cause trouble in exports, file names, and downstream systems. Letters, digits, spaces, and hyphens are safe.

Depth#

Three to five folder levels is the sweet spot.

Site > Area > Equipment > (Metric)
Site > Area > Line > Machine > (Metric)

Too shallow and one folder holds four hundred metrics that nobody can scan. Too deep and every chart build becomes a click marathon, and the tree scrolls horizontally.

If you find yourself at seven levels, look for a level that is not doing real work — often a redundant grouping with a single child.

Balance#

Watch for lopsided trees. One folder with two hundred metrics beside four folders with three each usually means the big one needs subdividing and the small ones should merge.

An area with a single child folder is a candidate for flattening, unless that child is about to gain siblings.

Where to put things that are not equipment#

Real models always accumulate content that does not belong to a machine.

Plan for growth#

Ask what the plant looks like in five years. A structure with room for Line 3 is better than one that has to be reorganised when Line 3 arrives.

Concretely: create the area folder even if it currently holds one line; use numbering that extends; and keep the top level to the handful of areas that will still be there after the next expansion.

Model attributes and the tree#

Attributes inherit down the tree, so folder structure and attribute strategy are the same design problem.

Setting Line Number on each line folder lets one templated expression resolve the right value for every machine beneath it. That only works if the tree puts the machines beneath the line — which is another reason structure comes first. See Model Attributes.

Reviewing an existing structure#

Signs a structure needs attention:

• Users ask where to find things that already exist
• The same measure exists in two places because nobody could find the first
• Folder names contain New, Old, Temp, Copy, v2, or a year
• One folder holds an order of magnitude more content than its siblings
• Similar equipment is arranged differently in different areas
• Templates cannot be applied because no two instances have the same shape

None of these need an immediate restructure. All of them are worth fixing during the next substantial change to that part of the model, since moving content affects attribute inheritance and template linkage.

Document the convention#

Write the rules down — depth, naming, numbering, where non-equipment content goes — and keep them with the model. A page of conventions is what keeps the fifth person to touch the model from inventing a sixth style.

See also#

• The Model Tree
• Model Attributes
• Templates: Concepts
• Units of Measure