Documentation for developers: A gift to your future self

A presentation at Florida DrupalCamp in February 2024 in Orlando, FL, USA by Kurt Trowbridge

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

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

Your memory is an unreliable narrator. 11

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

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

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

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

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

Kurt Trowbridge
@kurttrowbridge

1 / 43

Being an effective developer is more than just writing clean code. Documentation is an important skill that has numerous benefits to developers and their teams throughout the life cycle of a project—whether in the form of meeting notes, decisions made during development, or technical implementation details. But even beyond that, these notes have long-term benefits for maintaining projects and building team skills.

In this session, attendees will learn best practices on writing effective technical documentation. Early in the course of a web development project, it helps with the early planning and decision-making that help make a project successful. Later, it provides clarity that eases website maintenance and helps build collective knowledge that your team can build upon in future projects. And as artificial intelligence tools play more of a role in our daily workflows, the value of written documentation will only increase for you and your team. This session will highlight how an early focus on documentation, written by and for developers, can have lasting benefits.

Documentation for developers: A gift to your future self

Link for this presentation:

HTML code for embedding:

Share on social media: