Documentationfor developers
A gift to your future self

Kurt Trowbridge

Front-End Development Team Leader

Gravity Works Design + Development

2

Content types · Nodes · Fields · Taxonomy vocabularies
Display settings · Templates · Image styles · User roles
Permissions · Views · Blocks · Modules · Plugins · Hooks
Workflows · Composer · Drush · Caching3

Content types · Nodes · Fields · Taxonomy vocabularies
Display settings · Templates · Image styles · User roles
Permissions · Views · Blocks · Modules · Plugins · Hooks
Workflows · Composer · Drush · Caching · Semantic HTML
Responsive design · CSS · Preprocessors · Modern JavaScript
Atomic Design · Accessibility · Performance · Typography
Build tools · DNS · Server management · Security · Git · CI/CD

3

Content types · Nodes · Fields · Taxonomy vocabularies
Display settings · Templates · Image styles · User roles
Permissions · Views · Blocks · Modules · Plugins · Hooks
Workflows · Composer · Drush · Caching · Semantic HTML
Responsive design · CSS · Preprocessors · Modern JavaScript
Atomic Design · Accessibility · Performance · Typography
Build tools · DNS · Server management · Security · Git · CI/CD
Task management · Meetings · Collaboration · Deadlines
Customer service · Understanding requirements · EmailScope creep · Professional development · Work/life balance...
3

Content types · Nodes · Fields · Taxonomy vocabularies
Display settings · Templates · Image styles · User roles
Permissions · Views · Blocks · Modules · Plugins · Hooks
Workflows · Composer · Drush · Caching · Semantic HTML
Responsive design · CSS · Preprocessors · Modern JavaScript
Atomic Design · Accessibility · Performance · Typography
Build tools · DNS · Server management · Security · Git · CI/CD
Task management · Meetings · Collaboration · Deadlines
Customer service · Understanding requirements · EmailScope creep · Professional development · Work/life balance...
3

There’s a lot to learn.

56Documentation benefits...

01

02

03

You, nowYour teamYou, in the future8Preparing & planningManaging the messy middle
Unlocking future potential
Effective > efficient

95174812218
10

Your memory is an unreliable narrator.

11

Component planning

Brad Frost12

Documenting your content model

Drupal Spec Tool
13

Development task planning (1/2)
Make your title actionable—startwith a ver
Identify a problem, and make thetitle the solutio
Include descriptions whencontext is neede
Don’t be afraid to rename tasks
or update descriptions later14

Development task planning (2/2)

15Documentation is the act of thinking and thenputting those thoughts on paper.

16

Even if you’ve already decided on the next step
you’ll take to resolve a problem, your mind can’t
let go until and unless you park a reminder in aplace it knows you will, without fail, look. It willkeep pressuring you about that untaken next step,
usually when you can’t do anything about it,
which will just add to your stress.
—David Allen, Getting Things Done
17

Preparing & planningManaging the messy middle
Unlocking future potential
Effective > efficient

18Miller’s Law

The immediate memory span of people is limited toapproximately seven items, plus or minus two.

19

??????????
20

(517) 481-2218
21

Benefits of chunking
Breaks down large tasks into
smaller, more manageable piece
Makes it easier to make progress
between meetings and in sparetim
Reduces cognitive overhea
Enables delegation and fasterfeedback

Eugenia Hauss

Chunking also prevents this.

22

Fog of uncertainty

Know your audience

Document where the right people are going to see i
Tailor information to what that audience need
Don’t assume—avoid words like “just” and “simply
Use visuals and external links for additional context

24Documenting code with comments
Good documentation is selfdescriptive, but include businesslogic where needeUse chunking to think throughthe code before you write i
Leave URLs as breadcrumbs toinspiration or earlier thinking

25

Development parallels
Write “escape hatches” like you
would an early return—letsomeone stop reading if it’s notrelevant to theThink of task templates like you
would a repeatable functio
Documentation-driven
development: use comments tohelp you plan your code

26

Naming things is hard...or is it?
Be clear, not clever
Use action-based variables (“getRoles,”“saveToken,” “prepareData”
Name state functions clearly, also startingwith verbs (“isOpen,” “hasProfilePicture”
Mindset: keep functions small, then namethem according to that function

27

Architecture Decision
Records (ADRs)
Document “invisible standards”
that are expected, but not yet
written dow
Include context about why thedecision was madShould exist for the long term,
but can change as technology
evolves28

Taking notes in meetings
Yes, developers should take notes too
Note important information, decisions,and next steps—don’t transcribe thefull conversatio
Use document templates for easy prep

Emojis help highlight nextsteps during a meeting.

29

Checking out
Before you wrap up ona task and switch tosomething else, takenote of where you’releaving oHelps project managers
stay in the loo
Reduces effort needed
to spin back up nexttime30Retrieving information from memory storage andbringing it into the focus of awareness, comparing
information, evaluating, deciding—all makedemands on the mind’s limited processing
capacity.
—Mihaly Csikszentmihalyi, Flow
31

Preparing & planningManaging the messy middle
Unlocking future potential
Effective > efficient32

Using docs to power AI tools

NotebookLM (Google)
33

Notion AISpeech-to-text
AI apps can help with meeting transcriptions, so you can focus on documenting
decisions, business rules, and next steps.

34

Documentation is a team sport.

35

Shifting left—why not documentation?

01
Testing

02
Security

03
Accessibility

36

04...Documentation?

Who on the team actually makes working
software? Only the engineers. Every other role islargely one of documentation.
—Dan Mall, Design That Scales37Collective knowledge strategies

01
Write as you learn

02
Rubber-duck03
Work in public

38

04
Answer questions
with a linkCollective knowledge provides resilience against:

01

02

03

Vacations

Sick days

Employee turnover

39

Preparing & planningManaging the messy middle
Unlocking future potential
Effective > efficient40

“Year of Efficiency”

Efficient teams:

Effective teams:

Adopt the mantra “move fast

Build with purpose andand break things

intentio

Value urgency over relevanc

Value relevancy over urgenc

Work in unstable

Make time to build processes

environments prone to errors

and practices that establish

and mistakesstability

42

Being effective means getting good at the thinking
and problem-solving that AI can’t do for you. 

Documentation helps speed up that process.
43How to make documentation happen

01
Build it into yourculture02
Do it little by little

03
Make it everyone’s
responsibility

44

04
Tend to yourgarden

Make documentation part ofyour definition of “done.”45

Thank you!