Technically speaking: improve your code with documentation

Thank you all for coming here to listen, talk about documentation.

Welcome to technically speaking, improve your code with documentation.

Before we get to the good stuff, I'll tell you why I'm here, why I care about documentation besides the fact that I am a technical writer.

We'll look at what makes good documentation and I'll show you some examples of some bad documentation.

I'll share the tech writer secret, which is understanding your audience.

Who are you writing for?

You'll learn what kind of deliverables you can be creating and how to create them.

What's the best time to start writing?

We'll talk about why docs should matter to you why, they matter beyond the fact that you're here listening to this, and I'll leave you with some final takeaways.

Hi.

As you heard, my name is Alexandra.

My pronouns are she/her.

I am a technical writer for Google Chrome.

I am on Twitter, I am on Masterdon.

I will be wherever we are next, and before I was a technical writer, I was a developer at a television station where the developers had been there for 5, 10, 15 and 20 years respectively.

I was supporting websites built in 1999.

And whenever I had to figure out how to do that, I had to go talk to the developer who built it, who was still working there, say, okay, where is this stuff?

And if I change something, is a bunch of stuff gonna break.

Please, tell me not a bunch of stuff is gonna break.

Obviously that's not sustainable.

Now I write documentation for the Privacy Sandbox Initiative, and my goal is to help every single reader understand the new Web privacy standards and APIs that we are building to help support a more private Web.

My audience is Web developers.

Also ad techs and government regulators.

A lot of government regulators, I'm not afraid of them.

Definitely not afraid of them.

And this work really is only possible with the help of engineers who are writing documentation, writing use case guides, explaining how every single detail of the code works to me so I can help translate that to a larger audience.

And I have great news for you.

I am not the only writer in this room.

You are all writers.

Congratulations.

It doesn't mean that you're writing long form documentation or essays.

You're definitely writing emails.

I'm confident most of you are writing some form of documentation or project guides.

You might be writing tweets or toots.

And I do believe that every company, every larger company should hire technical writers to support documentation efforts and transform the content into something clear, more understandable.

We have our expertise, having developers writing documentation is a supplement rather than a replacement.

But ultimately the work that I do, the work that developers do, it's different kind of writing.

So let's talk about what good docs look like by looking at what good docs aren't.

Good documentation is not Hamlet.

Good documentation isn't soliloquies or paragraphs of long, complicated language.

You don't need to try and sound smart to be smart.

Help your audience feel smart and empowered to build with your products.

When I was in school, I used a booklet, then online website, Cliff's Notes.

If you're unfamiliar with Cliffs Notes.

The purpose was to supplement Shakespeare's work with a modern translation so that you could understand what he was trying to say.

I often didn't, it's like this is these words, they are too much for me.

And if you're familiar with Hamlet, which I'm sure at least some of you are.

Anybody read Hamlet?

Yes.

Excellent.

Okay.

You remember this feeling then of the first time that you read it.

I wonder if you'll recognize the soliloquy from the modern translation.

'Life or death existence.

Is it better to live and suffer or should I take action to stop existing?' It's to be or not to.

Really iconic.

The thing that you know, even if you haven't read Hamlet, you've probably heard 'to be or not to be, that is the question'.

Fiery prose, like to be or not to be, no place in documentation.

Documentation most of the time should not be a creative writing exercise.

So let's leave all of the beautiful prose, the metaphors, the adjectives to novelists, essayists, and digital marketers.

Translation alone doesn't actually lead to understanding of the content.

Writing documentation isn't writing exactly what the code is doing.

It's adding extra context to help your reader be successful.

Translation might help some people understand what's happening, but that's really just the first step.

You always have to think about what you want your reader to learn and take away.

Good documentation is clear and concise.

Your job as a developer is to fully understand the products and features you support.

If not, while you're building it, by the end, I hope you understand the thing that you built.

And by writing this information down as documentation, you are more likely to understand the work you've done, be able to explain it to somebody else, and then remember it in the future when someone says, Hey, there's a website I need you to update.

I built it in 1999.

Can you make changes?

And while grammar is definitely important in a final published product don't, worry so much about that.

Worry about that later.

There are a lot of tools out there that can help you with grammar.

Worry about explaining the thing you're trying to explain.

Documentation should not just be sprinkled on top of your work.

Sprinkles, wonderful decorative crunch at the end of a dessert.

But documentation shouldn't be at the end.

It shouldn't be the last thing on your list added in a small supply.

It should be woven and integrated throughout your product.

Documentation should be like what makes confetti cake great.

I love confetti cake.

Integrate your writing throughout the process.

Everybody is happy.

Everybody gets to eat cake.

And there's a whole talk I'd love to give about writing accessible content.

Maybe I'll be able to come back and do that next year, but I'd be remiss in not spending just like a little bit of time talking about accessibility, not least of which is having documentation is inclusion.

Having documentation is part of the way in which you make your product accessible.

But here's a few more things to remember, especially when writing for people with disabilities.

First use inclusive language.

This starts with self-reflection in the ways that we've internalized ableism, racism, and sexism in our everyday life.

We cannot write better without recognizing the ways in which we have failed and we can do better.

If your content is on a webpage, you should be using semantic HTML.

This means that your headers are not just visually larger than the body text, but it's actually represented by the proper header structure, h1, h2, h3, et cetera.

And write meaningful alt and link text.

If there is one thing you walk away from this talk with, stop using 'click here'.

I'm on a mission.

I wanna ban it.

Let's get rid of it.

We can all do this together.

Use meaningful link text instead.

You could use the title of the webpage that you're linking to, or the pdf.

You could link the summary of what the reader expects to learn.

This, this is so important, please down with, 'click here' up with contextual link text.

Okay.

You got some tips on writing, but before we actually start creating our documentation, it's really important to know who we're writing for, you must clearly understand who your audience is in order to properly meet their knowledge needs.

But before we get to our external audience, let's talk about somebody you should care really deeply about–yourself.

We all love ourselves.

Future you.

The best way to understand the work that you do and explain it to others is to write documentation.

It's possible that past you, before you started, wrote a project doc where you defined all the things that you expected to build.

I've read dozens of those.

In fact, my work at the Privacy Sandbox, a lot of what we do is write explainers that are talking about a potential future API that could support a certain use case.

But that's not the end.

It iterates.

A lot over time, over months, sometimes over years.

And that process where we end up at the end and the original project doc, they are not the same thing.

Writing documentation is supporting what the end thing ended up being.

It's possible that you always build exactly what you plan.

Perhaps you have a plan, you see it through.

Everything is great.

I wish that for, all of you truly.

Or perhaps like me, when I was nine, I thought I was going to be an actor on the stage.

As mentioned I, did work off Broadway for a period of time, but here I am, on the stage.

It's a little different than what I expected.

When writing documentation for yourself, you are filling the gap between what you thought the product would be and where it ended up.

And often our colleagues rely on our documentation too.

There's context that they have that the external reader doesn't have.

They, know all the acronyms.

They know the thing that you were supposed to build that it didn't end up quite being, they know why you changed your plans, but documentation can assist your colleagues when you're on vacation.

It can support the next developer who steps in and takes your job when you've moved on to something super awesome and better your next career.

My team has been incredibly supportive as I got to travel literally around the world to stand here in front of you.

And if you squint really hard, you might recognize some of the faces in this picture as people you'll see in the front end engineering track.

I won't name names.

Good.

But let's move our attention external.

Your audience might be developers, might be marketers or, another profession.

I think about the audience for the privacy sandbox.

I've been talking about us Web developers, browser vendors, ad techs, government regulators.

So think about it.

Who needs to read the documentation that you are writing?

Perhaps you work for a tech company and you've created a new speech to text API, your reference documentation can be auto-generated.

Love that, love auto generation, but that's not enough.

We can do better, share some overview materials share some integrations, some examples.

That sort of work is tremendously valuable to helping people actually onboard and use your product.

Perhaps you're a freelance Web developer and you're supporting building websites for smaller clients, and you've customized a CMS for them, and they email you on Saturday night and say, oh my God, there's a typo on the front page.

I need your help.

Write some documentation so you don't get those emails.

Or at the very least, so you can say, as per my documentation, see page six.

Thank you.

Among your audience, there will always be technical practitioners who are hands on with the product.

They're the beginners, the folks who might be new to tech or who might just be new to your product, and they're the experts, people who have been around for a while, people who have enough experience that they can just jump into something and figure it out without so much help.

And then there are the decision makers.

Those are the folks who might decide that they're going to use your product but not actually have the technical knowledge to implement it.

They want to see that documentation exists so they can hand it to the development team and say, run with this.

You can just, build things.

Ask yourself the following questions.

What is the prerequisite knowledge for my audience?

What do I expect them to know?

It might be an understanding of a certain framework or a certain product or APIs.

What is their purpose of reading?

Are they trying to learn about a new concept?

Do you have a new feature that's never been seen before and you want to set them up for success before they actually start building?

And finally, how much time do they have to actually read your documentation?

My dream of course, is people are spending so much time with my docs.

They love them, they read them, they think this is everything to me.

They put themselves to sleep at night with it.

That's, just a dream that is not real.

Most often people have a lot less time.

So think, about helping people who do have less time, still learn what they need to learn.

It can be really hard to ask yourself all of these questions and to think about what kind of documentation you need to create.

Sometimes we forget how much we know when you're deep in something, you use acronyms that you, don't even realize you're using.

On earlier slides the slides about accessibility.

I had a link that include included a 11 y.

Which stands for accessibility.

If you aren't in the accessibility space, you might not have known that.

I try really hard not to use acronyms, but it's, hard to remember what you don't, to remember what you know and not what you don't know.

That's called the curse of knowledge, and we all make mistakes.

Ask people who have less expertise to review your work, and they'll probably catch stuff that you couldn't have caught on your own.

Once we know who we're writing for, then we can decide what documentation best meets their needs, and when we should be writing it.

Often the best place to start with documentation is code comments.

I loved code comments.

I know it's it might be controversial.

There are people in this room probably who are like, Ugh, code comments.

No.

But the best part about these docs is that you can write them while you're developing.

The machine does not care about your comments if they're written properly.

One of the products I used to cover was called Google Publisher Tag and that was otherwise known as GPT.

GPT needs a lot of comments.

I, was told that back when GPT first started, it was a single line of JavaScript.

It just displayed ads for you.

No problems magically worked like that, not so much anymore.

It needs a lot of comments and those comments are really key to helping the developers and the ad manager interface users talk to each.

The thing about GPT is it has really specific rules for how to define your ad space.

And unless you're told explicitly that you need to perform certain actions, your code will break.

Not a great experience.

So the comment is what gives the developers context, it helps support them.

There are two functions in this code.

defineSlot and addService.

Those are self-explanatory to anyone in the ad space who's been working in Ad Manager.

You don't need to explain what those functions do.

I want to draw attention to the comment that matters.

The comment that if you don't listen to it, breaks your code.

For multi-size ad slots, declare slot sizes in the same order as in the ad manager UI.

What that means is when somebody inputs four different ads in the ad manager backend, they have to be input in the code in that exact same order or it breaks.

Not, again, not a great experience, but that comment is really key to making sure that the developers and the interface users talk to each other because that is not the same person, almost never the same person.

Once you're ready to start sharing your work, you should compile your Read Me, summarize the Project, help, extra helpful context to your future self, to your colleagues, to external users.

You don't need to publish open source projects to have Read Mes.

I wish I had a lot more Read Mes on internal projects.

And in fact again, the second thing, if you take one thing away from this, write more docs for your colleagues internally.

We really, appreciate it.

One example I really appreciate is Size Limit by Andre Sitnik, which is a performance JavaScript plugin.

It clearly defines what's in the code repository.

It links to projects that use this code.

It's, a great Read Me.

Okay.

What's in a good readme?

Prerequisites and configurations.

The number of times I've seen a project and it hasn't said that I need to install something first.

It's really frustrating.

It's really frustrating.

Make sure that you help prepare your users for going into your project before they've even gotten into the thick of it.

Instructions.

It could be that this is a massive project that we're talking about.

You don't need to have instructions for how to do everything in this one document.

You could link out, just have the instructions for how to install.

And repository support.

How does somebody contribute to this project, if it's open source?

Who are you?

How does somebody contact you?

Or perhaps, you don't want them to contact you, so you leave that information out.

I understand that.

And license.

Please, if it's an open source project, include a license.

I am not a lawyer, but I know the lawyers would tell you, please include a license.

Please include a license.

And it's also important to write step-by-step instructions.

These can be internal facing, which means again, you are supporting your colleagues and your future self and your successor be successful with your projects.

Or it could, they could be external facing, meaning that you're helping your user use your product.

The from basic step by steps to advanced tutorials, having these makes a big difference in people actually being able to use your product.

How much information you give is dependent on who your audience is.

Let's look at an example of hot chips.

Two steps, fry potatoes, eat.

I wouldn't know what to do with that.

I don't know how to get the end result.

Perhaps if I was an expert chef, I don't actually need the instructions.

I know how to make chips.

So let's look at a, hot chips recipe for more of an average home cook.

It lists, tools, ingredients.

It has nine steps.

It tells me what temperature to have the oil at to fry them twice.

That's the secret to having really crispy chips.

This, version is much more accessible to an average home cook.

And the last part of creating new products or features and creating documentation is supporting them with release notes.

A release note can be an announcement of specific changes or a new product or deprecation.

Let's talk about this one.

I hate it.

' Bug fixes, performance improvement'.

I know.

I personally have 40 of those on my phone right now for the different apps that I have delayed updating.

No one tell anyone.

Don't tell my employer.

And I know sometimes, again, lawyer says to you, you can't tell people why we needed to make updates.

That is need to know information.

So having something is better than nothing.

But, we can do better than this.

So let's look at a better release note from an app that I really like.

Signal.

What I like about this release note is it starts with the new feature announcement.

Stories are now in Signal, everybody has stories now.

I guess.

Share disappearing text images and video updates with select friends or groups that automatically disappear after 24 hours.

So just in case you're not familiar with the concept of stories, the feature is briefly explained in one sentence.

Love that.

And as a bonus, the best part about this release note to me says, if you don't want to see or share stories, you can opt out of it in your settings.

What release notes do you see that say, here's a new feature and here's how you opt out.

I love that.

That's great.

But really the takeaway from this is that the best release notes provide useful, meaningful, and informative content.

They don't say nothing.

They don't say bug fixes.

They, tell you actually what happened.

And with all of these examples of documentation, it's a lot.

I recognize that.

You can best set yourself up for success by using templates.

Even technical writers.

I have a lot of templates that I use.

It really helps you remember the questions that you need to ask and answer yourself and helps set you up to help your audience's level of expertise.

If you have technical writers at your disposal, ask them for help.

They're going to be thrilled to offer that to you.

And if not, I have some templates.

I'll share that link again at the end of the talk.

In addition to traditional documentation, and I do mean in addition to not as a replacement, blog posts are great casual content.

On my current team, the technical writers and devrel team publishes content for two audiences.

First, our developers building with Google Chrome specifically all of the new features, and then there are all Web developers.

That audience that is building cross browser performant sites, developing optimal UIs, keeping up with the latest Web trends.

Web dot dev is our platform for that audience, for all Web developers, and we aim to publish documentation that is broadly used by all browsers on MDN.

The blog that we have really covers timely news.

It covers the, different sorts of things happening on the Web, use case examples, et cetera.

The blog is not a replacement for our documentation.

What makes a good blog post?

Tell a story.

The best stories are easily told by starting with a problem.

This is the problem that I faced.

Then move on to challenges.

I was trying to solve this problem, but I faced X, Y, Z along the way, and then end with the solution.

It all ended well in the end, right?

Or if it didn't, be honest.

Sometimes we write blog posts about why we fail.

These stories are best told in the context of time.

There's a timestamp often on our blogs and I really appreciate that as a reader because I know, oh, this blog post is from 2011.

I'm not sure that the advice they're gonna give me is still relevant.

Keep those timestamps.

Okay, so now you might be wondering, so what, I know I should write docs.

Why does this actually matter?

Can't somebody else do this?

Writing is active learning.

Writing is significantly more effective in helping you learn than reading is, and that's not my observation.

Eric Maser, who is a professor at Harvard University, came up with the idea of the flipped classroom.

This means that students learn something, read about something, and taught their fellow students this new concept, and they learned better by teaching it back to fellow students.

When I got my first tech writing job, I was tasked to containerize an application with Docker.

Didn't know what containers were, didn't know what Docker was.

I was like, okay where do I, start?

Obviously, I started with Docker's documentation.

I read through it.

I wrote down every step and every time I failed, and then I created documentation for my company's users to containerize their applications.

I did a better job teaching by actually writing the instructions.

Your knowledge is power.

If you are a developer who says this doesn't need documentation, you are talking from a position of immense privilege.

Just the existence of documentation makes your product more accessible to all people, to people from underrepresented groups.

It, makes it so that other people can build with you.

Documentation is a part of inclusion and it's 2022.

There's no excuse to not be inclusive.

100% of developers who write documentation are better than those who don't.

Is this a tested statistic?

Thank you.

Yes.

We all support this.

Is this a tested statistic, like in Henri's presentation?

No, but we all know.

We all agree.

It's true and I love that for us.

And I know your time is precious.

Your time matters.

I know that at most companies, if you were hired as an engineers, docs are not a part of your performance review, but they should be.

Documentation is validation of your expertise.

So if anybody in here is a manager, manages an engineering team I, beg of you, I implore you.

Please include documentation as a part of the review process.

It matters.

And while I hope you, you feel more empowered to write quality documentation I know that really, we just need that extra actual incentive of our job is being judged based upon it.

Okay.

We all agree, we clapped.

We love it.

We love documentation.

We are ready to start doing it a bit more.

Here are some final practical takeaways for you to help you be a more successful documentation writer.

Keep it concise.

You know who wasn't concise?

Shakespeare, went on and on, and it's we get it.

Okay.

Hamlet's depressed, it's fine.

The the prose like that doesn't belong in your technical documentation, not even in your blog posts.

If the zombie apocalypse were to happen, you wouldn't say 'warning, those who are once alive are now dead, and they are rising from the ground and they're rotting and they're running after us.

Yes, that would've been, that would've been a wild choice of yours.

You would say, 'zombies run'.

It's enough . Be thorough.

Don't skip steps for the sake of brevity.

Make sure that your users have every single thing they need to succeed.

If you can ask for help, ask for feedback.

Before you publish ask your colleagues to take a look.

After you've published.

Ask for feedback from your customers.

I, know that can come with complaints about things that are totally irrelevant.

I know that happens to all of us, but in that, there are always people who ask questions and make you think, huh, I guess I didn't write about that.

And then you can improve your documentation.

And finally, if you get to the end of your project and you haven't written anything, you're gonna be overwhelmed, you don't wanna do it.

Often, you're not being judged on it, et cetera.

You know the most about your project as you're in the process.

Write while you code, write code comments.

You can transform a lot of that into documentation later.

Remember, write like you are a piece of confetti cake.

Sprinkle it throughout the coding process and you will have something clear, conscious, and completely understandable.

Thank you.