What to Document in the Drupal Implementation and Why

This document explains what should be documented in the technical wiki and why it is essential for long-term maintenance, debugging, and successor friendliness.

1. Why Documentation Is Needed

As the system grows, it becomes impossible to remember:

which View controls which output
which field is translatable
which form mode hides which fields
which CSS hides which buttons
which custom module alters which form
which display mode is used where

Without documentation, debugging becomes guesswork.

2. What Must Be Documented

The following categories cover the entire Drupal implementation.

2.1 Content Types

For each content type:

Fields (name, type, translatability)
Form display (widgets, hidden fields)
Display modes (default, teaser, publisher view)
Special behaviors (auto-generated values, computed fields)

2.2 Views

Create a master index listing:

View name
Purpose
Displays (page, block, feed)
Contextual filters
Relationships
Where it is used (menu, block, link)

Each View gets its own technical page using the template.

2.3 Custom Modules

Document:

What each module does
Which hooks it implements
Which forms it alters
Which fields it touches
Which Views it interacts with

This prevents “mystery behavior”.

2.4 CSS Overrides

List:

File name
Selectors used
Purpose of each rule

CSS is easy to forget and hard to debug.

2.5 Multilingual Configuration

Document:

Which fields are translatable
Which are shared
How translation workflow works
Which tabs are hidden
Language negotiation settings

This prevents multilingual chaos.

2.6 Permissions and Roles

Document:

Which role can edit what
Which role can translate
Which role can see publisher view
Which role can manage assets

Permissions often explain “why something is missing”.

2.7 Asset Architecture

Document:

How assets are linked to records
Which View displays them
How the asset-chain works
How the modal behaves (if any)

2.8 UI Customizations

Document:

Hidden buttons
Hidden tabs
Custom form modes
Custom display modes

These are easy to forget and hard to rediscover.

3. How to Organize the Documentation

Recommended structure:

/Technical/Content Types/
/Technical/Views/
/Technical/Modules/
/Technical/CSS/
/Technical/Multilingual/
/Technical/Permissions/
/Technical/Assets/
/Technical/Record View/

Each page uses the same template for consistency.

4. When to Document

Document immediately after implementing a feature:

not the design
not the intention
but the actual implementation

This prevents forgetting crucial details.

5. Benefits

Faster debugging
Clear overview of system behavior
Successor-friendly architecture
Reduced risk of breaking workflows
Confidence when making changes