Documentation for developers: A gift to your future self

Documentation for 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 · Caching 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 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 · Email Scope 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 · Email Scope creep · Professional development · Work/life balance… 3

There’s a lot to learn.

5

6

Documentation benefits… 01 02 03 You, now Your team You, in the future 8

Preparing & planning Managing the messy middle Unlocking future potential Effective > efficient 9

5174812218 10

Your memory is an unreliable narrator. 11

Component planning Brad Frost 12

Documenting your content model Drupal Spec Tool 13

Development task planning (1/2) Make your title actionable—start with a ver Identify a problem, and make the title the solutio Include descriptions when context is neede Don’t be afraid to rename tasks or update descriptions later 14

Development task planning (2/2) 15

Documentation is the act of thinking and then putting 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 a place it knows you will, without fail, look. It will keep 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 & planning Managing the messy middle Unlocking future potential Effective > efficient 18

Miller’s Law The immediate memory span of people is limited to approximately 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 spare tim Reduces cognitive overhea Enables delegation and faster feedback 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 business logic where neede Use chunking to think through the code before you write i Leave URLs as breadcrumbs to inspiration or earlier thinking 25

Development parallels Write “escape hatches” like you would an early return—let someone stop reading if it’s not relevant to the Think of task templates like you would a repeatable functio Documentation-driven development: use comments to help 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 starting with verbs (“isOpen,” “hasProfilePicture” Mindset: keep functions small, then name them according to that function 27

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

Taking notes in meetings Yes, developers should take notes too Note important information, decisions, and next steps—don’t transcribe the full conversatio Use document templates for easy prep Emojis help highlight next steps during a meeting. 29

Checking out Before you wrap up on a task and switch to something else, take note of where you’re leaving o Helps project managers stay in the loo Reduces effort needed to spin back up next time 30

Retrieving information from memory storage and bringing it into the focus of awareness, comparing information, evaluating, deciding—all make demands on the mind’s limited processing capacity. —Mihaly Csikszentmihalyi, Flow 31

Preparing & planning Managing the messy middle Unlocking future potential Effective > efficient 32

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 is largely one of documentation. —Dan Mall, Design That Scales 37

Collective knowledge strategies 01 Write as you learn 02 Rubber-duck 03 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 & planning Managing the messy middle Unlocking future potential Effective > efficient 40

“Year of Efficiency”

Efficient teams: Effective teams: Adopt the mantra “move fast Build with purpose and and 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 mistakes stability 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 your culture 02 Do it little by little 03 Make it everyone’s responsibility 44 04 Tend to your garden

Make documentation part of your definition of “done.” 45

Thank you!