Documentation for developers: A gift to your future self

A presentation at Drupal GovCon 2024 in August 2024 in College Park, MD, USA by Kurt Trowbridge

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) 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

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

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

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

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

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

Kurt Trowbridge
@kurttrowbridge

1 / 50

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: