Anyone who has worked closely with me, or followed on social media [, ], will have seen a post or comment to the effect of:

Names and dates on docs. Every time. Don't forget.

This is most often tacked onto design documents lacking inline attribution, and is phrased provocatively to make it sticky.

Why do I care enough about this to be prescriptive — bordering on pushy — when colleagues accuse me of being Socratic to a fault about everything else? Because not only is unattributed writing a reliable time-waster, the careers of authors hang in the balance.

Having to work to find the best person to discuss a topic with is annoying, but in large organisations, the probability of authors having work appropriated without credit goes up when they fail to claim ownership of their writing. It should go without saying that this is toxic, and that functional engineering cultures look harshly on it. But to ward off bad behaviour, it helps to model what's healthy.

The best reminder to cite work is for authors to name themselves. Doing this increases their stature, unsubtly encourages others to link and cite, and leaves a trail of evidence for authors to reference when building a case for promotion.

The importance of evidence to support claims of design work in technical fields cannot be overstated. Having served on hiring and promotion committees for many years, I can unequivocally say that this collateral is often pivotal. The difference between "[x] promote" and "[x] do not promote" often comes down to the names on documents. Reviewers will pay attention to both the authors list and the propensity of design doc authors to cite others.¹

Weighing Up Inline Attribution

In response to unsubtle nudges, several recurring arguments are offered against explicit authorship notices.

"These blocks detract from readability."

This is fair, but does not outweigh the needs of future readers who may be working to trace a chain of events or ideas. Nor does it outweigh the needs of authors for credit regarding their work at a future date.

"There's already an edit log."

This crutch fails in any number of ways:

• PDFs and printed copies do not include authorship data that is not in body text.
• Some systems (e.g. Google Docs) do not make the history available to non-editors.
• Documents may be copied or re-published in ways that disconnect the content from the original revision tracking system; e.g., in a systems transition as part of an acquisition.

Moreover, design is a complex and collaborative process. Ideas and concepts captured in documents are not always the contribution of the person writing down the conclusions of a whiteboarding session. A clear, consistent way to give credit helps everyone feel included and encourages future collaboration.

"Our team is small.

This is usually offered as a claim of superfluousness. If everyone knows everything and everyone working in a system, why does attribution matter?

Perhaps a team is small now, but will it always be? I am not in a position to tell, and my interlocutors also lack crystal balls. Given the downside risks, attribution is a pittance of an insurance premium.

"Specifying an author elides the contributions of collaborators."

This is easily countered with invitations in comments and drafts for contributors to add themselves to the authorship section. Generous and collaborative folks — the sorts of people we want to promote — reliably add their collaborators to documents proactively and set the expectation that others will do the same. Over time, practice becomes habit, which crystallises into culture.

Minimum Viable Attribution

A final concern I hear is that these blocks require a great deal of upkeep. Long-form revision logs might be onerous, but the minimum viable attribution style only needs three elements: names, emails, and dates. These should be provided on the very first page, ideally just below the title.

The primary date always refers first drafting, even if that is before publication. If deemed necessary, authors can optionally add a "Last Updated" field below the primary date, but this is optional. Documents authored in a single sitting by a lone author should avoid extra visual noise.

Revision logs are generally unnecessary, and my personal view is that they distract from content; if they're a requirement (e.g., in a heavily regulated industry), record them in an Appendix, but do not remove minimum viable attributions.

Here's a screenshot of an explainer I helped draft many years ago showing the basic form²:

If a document is still an early draft, it can be helpful to put some indication in the title — I use a prefix like "[ Draft ] ..." — and invite collaborators to add themselves to the authors list by including an entry there of the form "Your Name <your_email@example.com>". Once a document is circulated widely, remove these inline markers.

FOOTNOTES

1. If you write technical design docs, it is always a good sign if you cite prior work and parallel efforts, including competing designs. Omitting those references is something that both technical and promotion reviewers are alert to and are primed to think poorly of. No design is entirely new, and it is a sign of maturity to give others their due. ⇐

2. Don't worry, all of these email addresses are now inactive.

   On the question of emails and spam in authoring public documents, views are split. I favour always using them, but understand if authors prefer other sorts of contact information; e.g., their personal website. Best not to be too fussy about this sort of thing, except to ensure that internal documents always contain email addresses. ⇐