This year I returned to Portland, to present at the awesome Write the Docs.

I wanted to share with this awesome community, seven core values I've used at OutSystems and Docker. These values have helped me change the company culture, and ensure we can ship amazing products.

You can watch the recording of my presentation on youtube. But I also decided to share with you a written version. Here it is, enjoy it!

Today I want to talk about seven values of effective tech writing teams. But before I tell you more about these values, I have something to confess.

I'm a skeptic! I really am.

And every time I see something like the 7 habits of highly effective people or the 8 secrets of success, I start wondering "really? Is that all it takes?" It's not that I don't trust the people who come up with these books. I do. You see, my problem is that success or effectiveness are words without any meaning.

Success or effectiveness only have a meaning if you have a specific goal in mind.

And a goal can be something like:

• I want to have more money,
• I want to have more time,
• I want to be able to influence more people.

And now here's my problem.

It's 10 PM, and I'm working on a presentation called "7 values of effective tech writing teams", and I realize that I can’t go about explaining any of these values if I don’t explain what the goal of a tech writer should be.

So I started thinking about this. And then I remembered someone telling me that the goal of a tech writer is to teach people how to use a product.

That makes sense to me. But I also remember someone else telling me that the goal of a tech writer is to explain complex information in a clear way.

And while these goals make sense to me, I don't think they are ambitious enough.

I've seen great tech writers at work, and of course they teach people how to use products, and surely they explain complex information in a clear way. But there is something else. There is something more profound that guides them.

So, after thinking about this for a while, I started to understand that these two goals made sense a while ago, but probably not today.

A while ago, we could get away with products that were hard to use. When users complained about our products, we could tell them to read the manual, or do some training. And they would be OK with that.

But that’s not the world we live in today. Just imagine that you had to read the manual for every app you have on your phone, your tablet, and your computer. Or even the apps that you have on your watch.

That's just nonsense right?

So if we know that, we also know that our users are just people like you and I. They're using a bunch of apps and tools, and they don't really care about reading documentation or doing tutorials.

They care about using products that empower them to create amazing work!

With that in mind, I think that the goal of a tech writer today is to help build products that require no documentation.

And yes, I know that this might sound counter-intuitive.

But if we know that our users don’t really care about reading documentation, then we should be finding ways to improve the product to make it easier to learn. We should not be ignoring that!

And off course, when everything else fails, we can always create documentation to help our users. But creating documentation, should not be our primary goal.

So if your goal is to help create products that require no documentation, let me share with you seven values that can help you succeed at that.

If you want to help create amazing products that kick-ass, you should:

• Be the CEO (of the docs),
• Know the market, the product, and the users,
• You should ask why,
• And apply the 80/20 rule,
• You should be proactive,
• You should be treating words as tools,
• And you should be coaching others.

Lets jump to the first core value!

If you want to become effective, you need to become the CEO of the documentation, and act like one. As the CEO of the docs you need to create a vision for helping users complete their tasks.

You should be providing hints to users. Essentially creating good buttons, labels, tooltips or any other kind of microcopy that can nudge users in the right direction.

You also need to define how users can get help when they get stuck. Ideally, there should be a way to get help without having to leave your app.

You need to define what to document and where to document it. You should be creating just the minimal documentation necessary to get your users going.

And then finding where is the best place to make that information available. There are many options to choose from. You can provide information on the product documentation, a knowledge base, forums, blog posts, or even Stackoverflow.

You also need to define what doesn’t need documentation. This might sound obvious but it’s not. I see a lot of teams creating documentation that users will never read. All that time could be better spent doing something else.

Finally, you need to define how the information should be organized, to ensure your users can find what they need.

After creating the vision, you need to pitch it to the rest of the company.

You won’t be able to do everything on your own, so you need to sell your idea to developers, designers, support, and product managers.

By pitching your vision, you’ll be showing to the rest of the company that:

1. You have a vision. This is important because not every team has one,
2. That you’re not making arbitrary decisions.

Then you can’t just wait for things to magically change. You need to start working on implementing your vision.

The problem is that you might feel you don’t have any time for this.

It might seem that everyday there is something important that requires your attention. Someone will be asking you to fix typos, update screenshots, or do a bunch of other things that take a lot of your time, but have few value to your users.

So you need to schedule time to do strategic work, and avoid getting distracted by smaller issues.

If you spend all your time dealing with small issues like typos, screenshots, and things like that:

1. You’ll never be able to implement your vision,
2. You’ll not provide the best experience possible to your users.

And finally, you need to ensure others follow your vision. It’s not enough to have a vision, communicate it to others, and go about implementing it.

You’ll always be outnumbered by developers, designers, support, essentially the rest of the company.

So you need to continue reminding people about the vision, and ensuring every decision you and everyone else makes, is aligned with that vision. This means that sometimes you’ll have to push back and say no to people. And that’s OK!

And I know that this is easier said than done.

Creating a vision, pitching it, driving it, and ensuring others follow is hard!

But if you're no willing to work outside your comfort zone, you'll end up with a product that is hard to use. Lots of documentation, but few information that helps your users when they are stuck. Lots of unproductive discussions between you and the rest of the company.

Effective tech writers know their market, their product, and users. The old mantra about "knowing your audience" is no longer enough today!

Today, if you want to be effective, you need to know the market, the product, and the users.

Knowing the market allows you to understand the pain points that your company is trying to solve for your users. And if you know what the pain point are, you can help create a better product, and create documentation that empowers users, and doesn’t get in the way.

Knowing the product, allows you to create docs that are aligned with your vision. If users can learn something just by looking at the UI, don’t create documentation for that, no one will read it. If the product can be improved to make it easier to learn, then work with the design and development teams to achieve that. And if something is not intuitive and can’t be easily fixed, then create documentation for it.

But the problem is, how do you know whether something is intuitive or not? That’s why you need to know your users. If you don't know your users, you'll be creating something for yourself, not for them.

So what happens if you don’t know the market, the product, and the users?

It will be hard to pith your vision to the rest of your company. Essentially, your vision will be centered around yourself and your team, instead of the users.

It will be hard to prioritize your work, because you won’t understand what are the pain points of your users.

And it’s also possible that you end up creating documentation that is bloated, and explains everything, except what the user really needs.

Effective tech writers challenge others all the time.

They know that everyone tells them how to fix a problem they have, but they never explain what the problem is in the first place.

A developer might tell you that you need to document a new screen they've added to the product.

A product manager might tell you that you need to change the release notes to something they have.

The support team tells you need to add a bunch of disclaimers to the installation docs.

All of them tell you that this thing is really important, and needs to be done now!

But no one seems to explain why. So you need to develop the habit of asking why, and finding what is the problem that these people are trying to solve.

And do you know what happens when you don’t ask why?

You won’t be able to prioritize your work. You’ll always be stressed because your backlog keeps increasing and it seems that you can’t do anything about it.

You won’t be able to share your roadmap with the rest of the company, because you’ll be managing interruptions all the time, so it will be hard to create a roadmap.

You’ll be constantly fixing things that seem urgent but are not not. And most importantly, you may also end up fooling yourself into thinking that you’ve solved a problem, when in fact the problem was somewhere else to begin with.

Effective tech writers know that perfection takes time.

So even if you could create perfect documentation, whatever that means, by the time you were finished, the product would be completely different, and your documentation would be outdated and useless.

I don’t believe there are silver bullets to this problem. You need to prioritize your work, and only do the things with most impact to your users.

You need to be comfortable in creating the minimum documentation necessary to get your users going. Then you need to ship that, and iterate based on real user feedback, and not only your gut feelings.

If you don’t apply the 80/20 rule you end up working a lot, but you’ll not be solving the major problems your users are having. You also won't have any time to do strategic work.

You’ll be constantly fixing things that seem urgent but are not. And you’ll be constantly stressed, because you only see your backlog increasing. When the reality is that most of the items on your backlog have almost no impact to your users.

Effective tech writers are proactive and don't wait to be told what to do. After all, if you have a vision you need to go about implementing it. But finding excuses is easy!

You might tell yourself that your manager won't let you implement your ideas. Or that everyone ignores your ideas. Or that your competition has more resources, and that’s the reason they can do so much. Or you might tell yourself that you’re only called at the last minute, so you can’t change anything.

Or you might tell yourself that your job description is only to create documentation, so you should not be doing anything else besides that.

And I know that some of you are thinking that these are not excuses.

You might be thinking that this is the reality in your company and you can’t do anything to change that. But I don't believe that to be true. Let me explain you why.

Not so long ago, I remember designers complaining about the same things.

They complained that their managers wouldn't listen to them. They complained everyone ignored their opinion. They complained that their competition had more resources. And they also complained that they were only being called at the last minute with the hopes they could help fix the project.

You see the parallel here, right?

The only excuse you've never heard from a designer was "That's not my job description".

Instead of complaining all the time, designers were proactive, they learned new skills, and they’ve adapted.

And look where they are now!

Management listens to what designers say. There are even companies that have a VP of design reporting directly to the CEO. Everyone values their opinion. There definitely more design budget than ever before. And designers are included in the project since day one.

So if you're proactive, and don’t let yourself be defined by your job description, I think you can help revolutionize your company, and also the tech writing industry. But for that, you need to be willing to work outside your comfort zone.

And if you're not proactive...

Everyone in your company will think you complain a lot, but don’t help fixing the problems you complain about. And You’ll also have lots of unproductive discussions with other teams. It’s always more productive to discuss a concrete proposal and iterate on it, than to discuss vaporware.

Effective tech writers treat words just as they treat any other tool.

Let me explain what I mean by this.

If you’re a developer, you know that a programming language is just a tool to create software or apps.

So as a developer you don’t care whether you’re using C, Python, or Javascript. You only care whether you’re using the best tool for the job or not.

And as a developer, you also know that every tool comes with its own limitations. When you stumble on a limitation, you have two options.

You can complement the language you’re using with something else. So you can use C and Python at the same time. Or you can change the language itself. This is what has been happening with Javascript lately.

Just like developers, effective tech writers know that the English, or any other natural language is just a tool. But this is a special tool. It’s a tool that allows you to transfer ideas from one person to another.

And even though natural languages allow you to transfer ideas, they kind of suck at their job. Sometimes the idea gets completely distorted. Other times the idea is lost on its way.

Fortunately we can do the same thing as developers do! We can either complement language, with something else.

Something like diagrams, code samples, screenshots, videos, or something else. Or we can change the language itself. You can change English to make it more effective at transferring ideas!

The problem is that we've all been tricked by our primary school teachers into thinking that we can't change a natural language. But that’s just not true!

Just like C, Python, or Javascript can be changed to make it easier to build software, English can be changed to transfer ideas more easily.

But please don't trust me on this, trust Shakespeare!

This guy didn't really mind breaking conventions and best practices. And in the process of doing so, he also ended up by creating a lot of the words and expressions we use today and don't even realize.

If you’re only obsessed with styleguides and writing best practices you might be doing a disservice to your users.

You might be creating art, not technical documentation. And this is a problem because you’ll not be empowering users, you’ll be distracting them from achieving their goals.

And you’ll also be constantly working on tactical projects like fixing typos, and rearranging sentences. Essentially you’ll be doing the work of an editor, when your users need you somewhere else, fixing bigger problems.

Effective tech writers go out of their way to share their knowledge with others.

They know that everyone is doing the best they can with the resources they have, and so they don’t complain about the writing skills of the rest of the company.

Instead, they coach everyone else, and leverage them!

Instead of asking developers to create a ticket for a problem they found, you can coach and empower them to to fix the problem themselves.

Sometimes, the time it takes to file a ticket, is the same time it will take to fix it. So effective tech writers end up creating resources that the rest of the company can use.

They end up creating:

• Presentations
• Style guides
• Blog posts
• One-on-one sessions

If you’re constantly complaining that no one on your company knows how to write, and you keep that knowledge to yourself, guess what’s going to happen?

You’re fighting against the rest of the company, so guess who’s going to win? And you'll also be seen as the bottleneck for your company. No one will understand why it takes you so much time to do your work.

So if you want to be effective at creating apps that need no documentation, remember that you need to:

• Be the CEO (of the docs),
• Know the market, the product, and the users,
• You should ask why,
• And apply the 80/20 rule,
• You should be proactive,
• You should be treating words as tools,
• And you should be coaching others.