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

Highlights

• I find that not every reader who purchases early access to my book wants to give me feedback about rough drafts.
• I figure out where all my time is going and think of ways to minimize time drains.
• I spend 10 hours reimplementing a web app from scratch that originally took me 300 hours to build.
• I continue to learn functional programming with Gleam, but I might be cheating.

Goal grades

At the start of each month, I declare what I’d like to accomplish. Here’s how I did against those goals:

Eric wrote about his newsletter subscriptions, and asked some friends to do the same. Here’s my entry.

Two words that are often confused: conformance and compliance. What do they mean?

Listening to this Muse song while reading is optional.

Conform to a standard

When something conforms to a standard, it “meets” or “satisfies” specific requirements in a standard.

For instance, in the case of WCAG, those requirements include that:

• the requirements in a specific Level are met (eg Level A or Level AA).
• the claim is about full pages only, not parts of them (eg not components).
• technologies are only used in accessibility-supported ways, or there must be alternatives with technologies that are (in that case, those technologies may not interfere by having unstoppable audio (1.4.2), keyboard traps (2.1.2), unstoppable moving content (2.2.2), or flashes (2.3.1).

Additionally, to claim conformance on a page that is part of a process, every other page in that process must also be conformant.

Examples:

• “this website conforms with WCAG”.
• “this website meets the 55 WCAG success criteria of WCAG 2”.

Examples of what wouldn't make sense:

• “this component conforms with WCAG” (it cannot, as it is not a full page; you could say something like “this component is built with accessibility in mind” instead; see Can components conform to WCAG?).
• “this website complies with WCAG” (see compliance below).

How conformance in WCAG works is likely to change in WCAG 3, which is still many years from being released. It's one of the things we're currently discussing on in the Working Group.

Comply with a regulation

Then compliance. Organisations can comply with regulation, for instance the laws and regulations that EU Member States adopted following Directive (EU) 2019/882, the European Accessibility Act.

Sometimes they show that they do, by showing that they conform to a standard. The European Commission sometimes commissions standards for this very purpose, via “standardisation requests”. For instance, the next update to EN 301 549, currently in the works, was mandated under M/587. It is likely to become what provides “presumption of conformity with the essential requirements” for the requirements of the European Accessibility Act, once published in the Official Journal of the European Union.

Other languages

In Dutch, we speak of “conformeren aan een standaard” (conform to a standard) and “naleven van een wet” (comply with a law).

In German, conformance and compliance are both called “Konformität”. One could distinguish between “Standardkonformität” (with a standard) and “Gesetzeskonformität“ (with a law).

That's it, I hope this post helps folks. More translations welcomed!

---

Originally posted as Conformance vs compliance, accessibility standards edition on Hidde's blog.

Reply via email

With the fate of Goo.gl in the balance and many URL shortening/redirection services being either expensive or spammy, I wondered if I could find a free/cheap way of achieving the same. So I got myself a short domain (CLXI.org) and looked at using a GitHub repo with pages to redirect URLs. Turns out, this is […]