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

Learning curve for popular CMS platforms 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) 5 Make your title actionable—start with a ver+ 5 Identify a problem, and make the title the solutio# 5 Include descriptions when context is neede 5 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

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

Miller’s Law The immediate memory span of people is limited to approximately seven items, plus or minus two. 18

?????????? 19

(517) 481-2218 20

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. 21

Document where you’re going to see it. 22

Documenting code with comments 0 Good documentation is selfdescriptive, but include business logic where neede0 Use chunking to think through the code before you write i# 0 Leave URLs as breadcrumbs to inspiration or earlier thinking 23

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

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. 25

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 26

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 27

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

Using docs to power AI tools NotebookLM (Google) 29 Notion AI

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

Documentation is a team sport. 31

Collective knowledge strategies 01 02 03 04 Write as you learn Rubber-duck Work in public Answer questions with a link 32

Collective knowledge provides resilience against: 01 02 03 Vacations Sick days Employee turnover 33

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

“Year of Efficiency”

Efficient teams: Effective teams: 6 Adopt the mantra “move fast and break things1 6 Build with purpose and intentioB 6 Value urgency over relevanc 6 Value relevancy over urgenc 6 Work in unstable environments prone to errors and mistakes 6 Make time to build processes and practices that establish stability 36

Being effective means getting good at the thinking and problem-solving that AI can’t do for you.
 Documentation helps speed up that process. 37

How to make documentation happen 01 Build it into your culture 02 Do it little by little 03 Make it everyone’s responsibility 38 04 Tend to your garden

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

Thank you! Slides, notes, and resources: KurtTrowbridge.com