feed.xml

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <generator uri="http://jekyllrb.com" version="3.8.6">Jekyll</generator>
  
  
  <link href="/feed.xml" rel="self" type="application/atom+xml" />
  <link href="/" rel="alternate" type="text/html" />
  <updated>2021-02-25T20:17:23+00:00</updated>
  <id>//</id>

  
    <title type="html">breno barreto</title>
  

  
    <subtitle>Hi there! My name is Breno and I'm a web development enthusiast and Senior Technical Writer at Nubank,  currently based in Rio de Janeiro. Here I write about stuff that interest me,  which typically revolves around content and software development - and how these things relate.</subtitle>
  

  

  
  
    <entry>
      
      <title type="html">The pain and gain of migrating from traditional Communications to the tech industry</title>
      
      
      <link href="/2020/03/12/the-pain-and-gain-of-migrating-from-traditional-communications-to-the-tech-industry/" rel="alternate" type="text/html" title="The pain and gain of migrating from traditional Communications to the tech industry" />
      
      <published>2020-03-12T00:00:00+00:00</published>
      <updated>2020-03-12T00:00:00+00:00</updated>
      <id>/2020/03/12/the-pain-and-gain-of-migrating-from-traditional-communications-to-the-tech-industry</id>
      <content type="html" xml:base="/2020/03/12/the-pain-and-gain-of-migrating-from-traditional-communications-to-the-tech-industry/">&lt;p&gt;I graduated in Journalism in 2011. At that time, I still had the goal of becoming a news reporter that would help change the world a little by investigating and exposing uncomfortable truths.&lt;/p&gt;

&lt;p&gt;It was an awesome drive and I’m happy there’s plenty of people in the world with similar ambitions. The problem for me wasn’t the nature of the drive, but the intensity. I wanted it but not that much.&lt;/p&gt;

&lt;p&gt;So I began a professional trial and error journey throughout many fronts in the communications field: press office, TV, public relations, internal corporate communications, book publishers… And eventually I realized a couple of discouraging facts:&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;The traditional communications field was crossing a deep valley in which there was a shortage of trust and money - and since I couldn’t see where in the road it would begin to climb that valley, I did not want to blindly impose the same gap on my career. Journalism would eventually come back to the game. But who knew when? I wasn’t in the mood to wait and see.&lt;/li&gt;
  &lt;li&gt;Working in a field such as this makes one forget there’s something else. While I was struggling to keep some excitement about my job even while editing a book about Pokémon Go in the publishing house where I’d entered to make art books (because the company needed to pay the bills), I began to understand there was an entire industry being leveraged by advances in digital technology, where people I’d met in school were now working with a smile in their faces (most of the time, at least), giving their best not to stop daily bleedings, but to keep pace with a thriving market.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;My understanding about how much I wanted that feeling grew at the same rate as my despair about not going anywhere within my original field. Previously, I’d always seen myself as a classic journalist, trapped in the rabbit hole where I had entered after dropping out of Computer Engineering in the Federal University of Rio de Janeiro, in the middle of a class about Python, to switch to Journalism in the same university - to my mother’s despair.&lt;/p&gt;

&lt;p&gt;I’d had my chance, and now here I was trying to remember what Python was, and JavaScript, and SEO, and Google Tag Manager… while pondering that maybe I did like all that stuff. And maybe there &lt;em&gt;was&lt;/em&gt; a place for me in that thriving market.&lt;/p&gt;

&lt;p&gt;But hey, liking this universe or not, I was still someone coming from a Communications background. For the tech industry, I quickly understood that my experience and skills framed me as a &lt;strong&gt;Content&lt;/strong&gt; guy. Someone who could create, organize and deliver content. Good enough, I liked that.&lt;/p&gt;

&lt;p&gt;So as the despair of not moving forward grew, it became more and more imperative to find a way through the gates of that universe, selling myself as this techie content guy. It was time to intensify my research and start sending applications. I researched every single tech company I could find in Brazil and tweaked my resume according to what I believed the company might want from me.&lt;/p&gt;

&lt;p&gt;But the truth is: I couldn’t really see anyone accepting my application. I visualized myself in one of the interviews that might come out of that effort and felt like a fraud. What did I actually know about that industry besides some buzzwords I’d seen in a couple of articles?&lt;/p&gt;

&lt;p&gt;I could lie to you and tell you that today, looking backwards, I realize this fear didn’t make sense. But it did. Because although I’m sure I had the necessary drive and ability to enter a tech company and learn the techie stuff in the move, it would have been really hard to make that clear and stand out from a stack of resumes without ever having worked in the tech industry.&lt;/p&gt;

&lt;p&gt;I certainly had much more important skills. And before you say the word “soft”, I will stop you right there. No, it was not only the soft skills. One thing we need to understand is that the specific skills someone from the Humanities bring from their educational background and professional experience are not “soft skills” only because they are from the Humanities. Hard and soft are not synonyms of Exact Sciences and Humanities.&lt;/p&gt;

&lt;p&gt;So, as I was saying, I had much more important skills than the technical stuff that would eventually come with the daily work. But what I did not have was something concrete to show. And if you don’t experience in the field and also don’t have someone inside the company who knows you and refers you to the job, &lt;strong&gt;you need something concrete you can show&lt;/strong&gt;. A person from Communications would probably think of a portfolio. And that’s a fine idea. But make it an online portfolio. Then attach a blog to it. Then start using Google Analytics for that blog, and learn how to take insights from there, then write about those insights. Then create a Facebook Business account, and start playing with ads to promote your best blog post, maybe go to the code of your website and play with the HTML and the CSS.&lt;/p&gt;

&lt;p&gt;I don’t know, I’m just dropping ideas here. My point is: if you want to be in the tech industry, take a step ahead of what’s expected of you and &lt;em&gt;be&lt;/em&gt; in the tech industry even before you are interviewed. While trying to actually make something, you will be building that concrete thing to show while at the same time learning a lot with your mistakes and accomplishments and incorporating the vocabulary to talk to people in tech. That is the beauty of the web: the knowledge is all there - usually not very well organized, but it’s there. Take as much as you can from it and build something with it.&lt;/p&gt;

&lt;p&gt;It’s a simple idea, but I can assure you the great majority of people invest no time and effort in that. Not even one or two hours a week. So when someone asks me how hard it is to migrate from traditional Communications to the tech industry, I’m pretty comfortable to say it’s not hard at all - if you are good in what you do. All it takes is humility to understand how much there is to learn, and then go learn some of it.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="market" />
      

      

      
        <summary type="html">I graduated in Journalism in 2011. At that time, I still had the goal of becoming a news reporter that would help change the world a little by investigating and exposing uncomfortable truths.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">One deliverable a day</title>
      
      
      <link href="/2020/03/09/one-deliverable-a-day/" rel="alternate" type="text/html" title="One deliverable a day" />
      
      <published>2020-03-09T00:00:00+00:00</published>
      <updated>2020-03-09T00:00:00+00:00</updated>
      <id>/2020/03/09/one-deliverable-a-day</id>
      <content type="html" xml:base="/2020/03/09/one-deliverable-a-day/">&lt;p&gt;I began my Journalism career as a producer on TV Globo, and there is one detail that comes frequently to my mind: while working there, I never went to bed without having completed the task of the day.&lt;/p&gt;

&lt;p&gt;It’s not that I was faster or more committed. What made it possible was that every single day I had the same simple task: putting a news piece on the air. And it was impossible to think it might not happen. After all, the news simply had to be broadcasted ー at the time and with the length someone else had determined. It was an unbreakable given.&lt;/p&gt;

&lt;p&gt;At that time (about ten years ago) I’d never even heard the word “deliverable”. It wasn’t and still isn’t part of the Brazilian journalistic jargon. So only today, working among developers in a software company, I may look back and say, “Gee, I had one really big deliverable per day.”&lt;/p&gt;

&lt;p&gt;I like to think of this in order to reinforce an important idea to my current self:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;When the deadline tightens, you find a way to deliver.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;And the way to deliver is probably not only to produce more, but mainly to better organize expectations and to dos.&lt;/p&gt;

&lt;p&gt;Think about when you were in school and needed to learn geography. Your teacher did not ask you to do a final exam explaining the workings of planet Earth from one day to the next. Instead, they asked you to do an exercise on rivers for the next day, then to do another one on mountains for the day after, and so on.&lt;/p&gt;

&lt;p&gt;But if they said that instead of one you had ten days to do the exercise on rivers, it would probably take you ten days. It’s an old story: a task expands through the entire time you are given to complete it.&lt;/p&gt;

&lt;p&gt;In fact, I like to think of work as a gaseous material. It can be compressed (but only to a certain point before causing an explosion), and the more compression, the higher the pressure. But when it comes to expanding it, it advances happily through all the available space.&lt;/p&gt;

&lt;p&gt;For content creators, it’s vital to find the balance between unbreakable deadlines and the space necessary to be creative. Because content needs two things that seem to be almost opposites: it needs to go beyond the four walls inside which our minds usually live and it needs to be as frequent and reliable as a clock. Finding the productivity mindset that will make it be both is what makes you grow fast.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="management-and-productivity" />
      

      

      
        <summary type="html">I began my Journalism career as a producer on TV Globo, and there is one detail that comes frequently to my mind: while working there, I never went to bed without having completed the task of the day.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Using active voice is a matter of courage</title>
      
      
      <link href="/2020/03/07/using-active-voice-is-a-matter-of-courage/" rel="alternate" type="text/html" title="Using active voice is a matter of courage" />
      
      <published>2020-03-07T00:00:00+00:00</published>
      <updated>2020-03-07T00:00:00+00:00</updated>
      <id>/2020/03/07/using-active-voice-is-a-matter-of-courage</id>
      <content type="html" xml:base="/2020/03/07/using-active-voice-is-a-matter-of-courage/">&lt;p&gt;Be true to yourself: when you say that “the task will be finished on time,” how much do you really expect this to happen? Aren’t you saying it with the hope that the task will be finished on time by itself? Aren’t you trying to take responsibility for the action off your shoulders and transfer it to the shoulders of the task itself?&lt;/p&gt;

&lt;p&gt;Whether or not that’s what’s going on, trust me: that’s how it sounds to your readers, even if they don’t consciously realize it.&lt;/p&gt;

&lt;p&gt;Every word has its personality, and some classes of words are stronger than others. Prepositions are timid links; articles are determined but sometimes intrude where they’ve not been called; adjectives are peacocks opening their tails whenever they have the chance.&lt;/p&gt;

&lt;p&gt;And then there are the verbs. Verbs are the saw in the hand of the carpenter, the brush in the hand of the painter. It is through them that we transform the state of things. If it were not for the verbs, we would still be lying on the grass waiting for things to happen, without even being aware of what it means to be or to wait.&lt;/p&gt;

&lt;p&gt;Maybe that’s why they cause fear: because using a verb is acting, and actions have consequences. Just as an inexperienced carpenter may be afraid of sawing the chair’s foot in the wrong place, thus destroying it, the inexperienced writer may be afraid of saying “This &lt;strong&gt;is&lt;/strong&gt; so”; “John &lt;strong&gt;did&lt;/strong&gt; such thing” ─ because with that she puts herself in the position of someone who knows how things are, and may be demanded for such knowledge.&lt;/p&gt;

&lt;p&gt;And that’s the point where she turns to the active voice, like a carpenter who leans the saw against the chair, hoping they both will solve their issue by themselves.&lt;/p&gt;

&lt;p&gt;Read aloud:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;The task will be finished on time.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;And now:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;I will finish the task on time.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;If the second option doesn’t make you much more confident, then there’s something wrong with you.&lt;/p&gt;

&lt;p&gt;That’s because the second sentence shows courage and confidence. The person who is saying it isn’t trying to hide behind the invisible hand of chance, which will make things happen (will it?), maybe with the help of an angel. The task will be finished… By someone… Maybe…&lt;/p&gt;

&lt;p&gt;So whenever you have the chance, &lt;strong&gt;choose the active voice&lt;/strong&gt;. By doing that, you will show to your readers that you are not afraid of what you’re saying. After all, if you’re not 100% certain of your words, it’s hard to expect that your readers will be.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="copywriting" />
      

      

      
        <summary type="html">Be true to yourself: when you say that “the task will be finished on time,” how much do you really expect this to happen? Aren’t you saying it with the hope that the task will be finished on time by itself? Aren’t you trying to take responsibility for the action off your shoulders and transfer it to the shoulders of the task itself?</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Docs done right improve your product</title>
      
      
      <link href="/2020/03/02/docs-done-right-improve-your-product/" rel="alternate" type="text/html" title="Docs done right improve your product" />
      
      <published>2020-03-02T00:00:00+00:00</published>
      <updated>2020-03-02T00:00:00+00:00</updated>
      <id>/2020/03/02/docs-done-right-improve-your-product</id>
      <content type="html" xml:base="/2020/03/02/docs-done-right-improve-your-product/">&lt;p&gt;Since I started recording episodes for my &lt;a href=&quot;https://brenobarreto.co//the-manuscript-podcast/&quot; target=&quot;_blank&quot;&gt;podcast&lt;/a&gt;, only a few weeks ago, I’ve already had the chance to talk to some pretty amazing content people, such as &lt;a href=&quot;https://idratherbewriting.com/aboutme/&quot; target=&quot;_blank&quot;&gt;Tom Johnson&lt;/a&gt;, &lt;a href=&quot;https://www.thenotboringtechwriter.com/&quot; target=&quot;_blank&quot;&gt;Jacob Moses&lt;/a&gt;, &lt;a href=&quot;https://everypageispageone.com/about/&quot; target=&quot;_blank&quot;&gt;Mark Baker&lt;/a&gt; and &lt;a href=&quot;https://www.splunk.com/en_us/blog/author/cgales.html&quot; target=&quot;_blank&quot;&gt;Christopher Gales&lt;/a&gt; (this last one still to be published).&lt;/p&gt;

&lt;p&gt;Of course, each of them has different thoughts on many aspects of the writing job, but one thought has emerged in every one of these conversations (yeah, probably due to my own interest in it, I’ll admit). It can be summarized like this:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;Looking at product development through a content-first lens doesn’t only improve the documentation; it improves the product itself.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;So let’s talk a little about it. Think of a product team gathering inside a meeting room to discuss the first steps of a project that will eventually lead to a new product or feature. Who are the people inside the room? You probably see a Product Manager; maybe the CEO, if the product is really important or the company is a small startup; designers; developers; a support engineer? Maybe someone from QA? If you’re really lucky, maybe even a UX Writer.&lt;/p&gt;

&lt;p&gt;You know where I’m going with this: the person you probably &lt;em&gt;won’t&lt;/em&gt; see in the room is the tech writer. And that’s not because nobody likes her, but because technical documentation is usually not seen as part of a digital product itself. Most of the time it is seen as an appendix. And when you draw a project timeline on the whiteboard and ask people where the appendix comes in, the obvious answer will be “in the end”, after everything that is core and important has been figured out.&lt;/p&gt;

&lt;p&gt;And what’s funny is that many times what is really an appendix will be included first, simply because it’s easy to think about it. &lt;a href=&quot;https://en.wikipedia.org/wiki/Law_of_triviality&quot;&gt;The bike shed’s material&lt;/a&gt; before the design of the nuclear plant.&lt;/p&gt;

&lt;p&gt;And what happens when the tech writer is finally called in is a series of unnecessary stumbles. After all, the feature is allegedly ready, so now the team needs to decide if:&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;It will be deployed without documentation - it can be done later;&lt;/li&gt;
  &lt;li&gt;They will hold the deploy while the writers rush to come up with something that resembles a piece of documentation (which is a poor way of working and, by the way, shows little respect for the writer’s job);&lt;/li&gt;
  &lt;li&gt;There simply won’t be any documentation - that’s a user’s problem.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Also, let’s think of something else: if she was not working on the product documentation, what was that lazy tech writer doing while the product team worked hard on developing the whole thing? Well, she was trying to cover for the inconsistencies in the previous features of the company that were also built without synchronous documentation work. Because - by not having been built with synchronous documentation work - they were born with usage gaps.&lt;/p&gt;

&lt;p&gt;Now you may be pondering that ensuring good usage is the job of designers - and they &lt;em&gt;were&lt;/em&gt; in the room during that first meeting. My answer is that you are, once again, underestimating the impact of the tech writer’s work on the development of the product. Designers are definitely essential, but they are so close to the product that they can never assume the position of the user. QA engineers are also essential, but they’re there to make sure nothing will break. They are also not meant to assume the place of the user.&lt;/p&gt;

&lt;p&gt;The tech writer, on the other hand, &lt;em&gt;is&lt;/em&gt; very much in the position of assuming the place of the user. In fact, &lt;strong&gt;the tech writer is usually the first user&lt;/strong&gt; of all. Only she can look at the product with the ignorance and curiosity that lead to the questions necessary to generate knowledge that matches the user’s mental model - which is to say &lt;em&gt;valuable knowledge&lt;/em&gt;. Because she is not the strategist nor the builder nor the tester. She is the learner an then the teacher. And in order to teach, she needs to use the product, not like someone who created it, but as users would.&lt;/p&gt;

&lt;p&gt;So what happens when the writer is in the room is that she will learn to use the product while the product team builds it. And in doing that she will teach you what you would only be able to learn much later, after the product is deployed, through tickets sent by angry users.&lt;/p&gt;

&lt;p&gt;“Tech writer” or “documentarian” are deceptive names when it comes to assessing the real impact of this position when it’s well used. Put the writer in the room and you’ll have a great ally in making a better product.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="tech-writing" />
      

      

      
        <summary type="html">Since I started recording episodes for my podcast, only a few weeks ago, I've already had the chance to talk to some pretty amazing content people, such as Tom Johnson, Jacob Moses, Mark Baker and Christopher Gales (this last one still to be published). Of course, each of them has different thoughts on many aspects of the writing job, but one thought has emerged in every one of these conversations.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Go build something</title>
      
      
      <link href="/2020/02/20/go-build-something/" rel="alternate" type="text/html" title="Go build something" />
      
      <published>2020-02-20T00:00:00+00:00</published>
      <updated>2020-02-20T00:00:00+00:00</updated>
      <id>/2020/02/20/go-build-something</id>
      <content type="html" xml:base="/2020/02/20/go-build-something/">&lt;p&gt;Hello, dear tech writing newbie.&lt;/p&gt;

&lt;p&gt;Not that you asked, but I’m writing this post to let you know that, if I were you, I would pick whatever technology you seem to like and go build something with it.&lt;/p&gt;

&lt;p&gt;Why? Mostly, because as a tech writer you will be producing content to help people build stuff. And to really understand their pain, you should first try to be a builder yourself.&lt;/p&gt;

&lt;p&gt;In doing that, you will probably come across documentation that will drive you mad. You will soon find yourself banging your head against the keyboard after realizing that a simple task that took you three hours to complete was actually unnecessary. You will read an article that tells you how to use a method to call an API and then test the deploy by using a Continuous Integration tool and then in the next half hour, you will find yourself browsing ten other articles across the web trying to learn what’s a method, an API, a deploy and a Continuous Integration tool.&lt;/p&gt;

&lt;p&gt;This will all be quite frustrating at the beginning because you will read a lot and do very little. You will probably tell yourself that this might not be for you; that there’s too much out there and you’re too old to start learning now; that everyone else has figured out the ins and outs of digital technology and you’ve missed the boat. Too late, what a shame.&lt;/p&gt;

&lt;p&gt;Well, live through that. It’s the hard part. I guarantee that at some point you will start connecting the dots. And that’s when things get fun.&lt;/p&gt;

&lt;p&gt;And in the process of reaching fun, you will have consumed a lot of good and bad documentation; complete and incomplete tutorials; well-organized and badly-organized developer docs. Wearing the shoes of your audience, you’ll have become much more prepared to work as a technical writer.&lt;/p&gt;

&lt;h3 id=&quot;need-an-idea&quot;&gt;Need an idea?&lt;/h3&gt;

&lt;p&gt;If you’ll be working with the web, HTML, CSS, and basic JavaScript are the go-to skills you’ll want to pursue in the beginning.&lt;/p&gt;

&lt;p&gt;So why don’t you create a personal blog for yourself using &lt;a href=&quot;https://jekyllrb.com/&quot;&gt;Jekyll&lt;/a&gt;? (Oh boy, I love Jekyll.) It simplifies a lot of things for you while still leaving room to play with HTML, CSS and JavaScript. You will also find the need to deal with the command line and with markdown. It may seem a lot at first, but these are all useful skills for a tech writer. Take your time and prioritize exploration over delivery. If you find yourself inside a loop of creating one incomplete project after another (been there), even better. The learning that comes with this &lt;em&gt;doing -&amp;gt; destroying -&amp;gt; iterating&lt;/em&gt; is priceless.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="tech-writing" />
      

      

      
        <summary type="html">It's a cliché to say the best way to learn is doing. It's also true. And if you want to be a better tech writer, there's nothing like wearing the shoes of your audience. So go build something and deal with other people's docs.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Why people still use self-closing HTML tags like</title>
      
      
      <link href="/2020/02/13/why-people-still-use-self-closing-html-tags/" rel="alternate" type="text/html" title="Why people still use self-closing HTML tags like &lt;br/&gt;" />
      
      <published>2020-02-13T00:00:00+00:00</published>
      <updated>2020-02-13T00:00:00+00:00</updated>
      <id>/2020/02/13/why-people-still-use-self-closing-html-tags</id>
      <content type="html" xml:base="/2020/02/13/why-people-still-use-self-closing-html-tags/">&lt;p&gt;HTML has two types of tags:&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Container tags&lt;/strong&gt;: the tags that need information inside. Because of that, you need to inform where the element starts and where it ends. For example, if you’d write a paragraph, you would type something lile &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;p&amp;gt;Hello World&amp;lt;/p&amp;gt;&lt;/code&gt;, where &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;p&amp;gt;&lt;/code&gt; is the opening paragraph tag and &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;/p&amp;gt;&lt;/code&gt; is the closing paragraph tag.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Empty tags&lt;/strong&gt;: these are the ones that don’t need any information inside. For example, in case you want to break a line, you just type &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;br&amp;gt;&lt;/code&gt;. There is nothing to be contained there, so you don’t need a &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;/br&amp;gt;&lt;/code&gt; (there is no such thing in HTML).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;OK, pretty basic stuff.&lt;/p&gt;

&lt;p&gt;And then we see all over the web things like &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;br/&amp;gt;&lt;/code&gt;. What the heck is that?&lt;/p&gt;

&lt;p&gt;Note that the forward slash in this case is after the &lt;code class=&quot;highlighter-rouge&quot;&gt;br&lt;/code&gt;, not before. This actually means &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;br&amp;gt;&amp;lt;/br&amp;gt;&lt;/code&gt;, which we’ve just that makes no sense. And it doesn’t.&lt;/p&gt;

&lt;p&gt;Self-closing tags like this come from the long-forgotten &lt;a href=&quot;https://www.w3.org/TR/xhtml1/&quot;&gt;XHTML&lt;/a&gt;, which was an attempt raised by W3C to extend HTML using the syntax of &lt;strong&gt;XML&lt;/strong&gt; rather than &lt;a href=&quot;https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language&quot;&gt;SGML&lt;/a&gt; - the original standard in which HTML was based. Until HTML5, there was still an attempt to define HTML as an SGML application, but HTML5 left that aattempt behind. (HTML4 was still defined by W3C as “an SGML application conforming to International Standard ISO 8879”.)&lt;/p&gt;

&lt;p&gt;The thing is XML is much more strict than HTML. For instance, if there is any error in an XML document, the entire document will simply not be rendered. Although there are advantages there, I can only imagine that a web based on XML would be constantly half broken.&lt;/p&gt;

&lt;p&gt;In its strictness, XML requires that every opening tag &lt;em&gt;must&lt;/em&gt; have a corresponding closing tag, no matter if it’s a container or not. So you would write &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;br&amp;gt;&amp;lt;/br&amp;gt;&lt;/code&gt;, which can be abbreviated by using &lt;code class=&quot;highlighter-rouge&quot;&gt;&amp;lt;br/&amp;gt;&lt;/code&gt;. Both mean the same.&lt;/p&gt;

&lt;p&gt;HTML5 doesn’t complain if it sees a self-closing tag like that, but only to keep compatibility. What actually happens under the hood is that the forward slash is ignored.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="weby-nuggets" />
      

      

      
        <summary type="html">XHTML has not been used for a long time, but a lot of people still use something inherited from it and completely ignored by browsers: self-closing tags.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Clarity vs. friction in Technical Writing</title>
      
      
      <link href="/2020/02/10/clarity-vs-friction-in-technical-writing/" rel="alternate" type="text/html" title="Clarity vs. friction in Technical Writing" />
      
      <published>2020-02-10T00:00:00+00:00</published>
      <updated>2020-02-10T00:00:00+00:00</updated>
      <id>/2020/02/10/clarity-vs-friction-in-technical-writing</id>
      <content type="html" xml:base="/2020/02/10/clarity-vs-friction-in-technical-writing/">&lt;p&gt;I believe that everyone who works with technical writing should read something about instructional design at some point. If not to become an instructional designer, at least to grab a picture of the techniques used to teach adults. After all, in the end of the day that’s what we’re doing.&lt;/p&gt;

&lt;p&gt;So for the past two months I’ve been leafing through books and articles that try to recommend ways to design, implement, and evaluate learning experiences, in hopes of finding insights that help me in my job. And insights I’ve found.&lt;/p&gt;

&lt;p&gt;One of them made me contrast two of our daily efforts: first, the one to be as clear, concise, and straightforward as possible; second, the one to escape boredom and create enough friction to make the learning experience more interactive and take the learner out of her passive position, stimulating the cognitive load.&lt;/p&gt;

&lt;p&gt;Some of the ways in which such friction may be created, according to the author of &lt;em&gt;Design for how people learn&lt;/em&gt;, are:&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;Tell stories;&lt;/li&gt;
  &lt;li&gt;Surprise the learner;&lt;/li&gt;
  &lt;li&gt;Create social interaction;&lt;/li&gt;
  &lt;li&gt;Show the learner “shiny things”;&lt;/li&gt;
  &lt;li&gt;Make the learner explain the subject.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;However, how do we do any of these without losing clarity or at least objectivity? Is it possible to tell stories in documentation? Is it feasible to expect the learner to engage in the learning experience with a more active approach?&lt;/p&gt;

&lt;p&gt;I believe it is, but only to a certain point.&lt;/p&gt;

&lt;p&gt;When we’re dealing with a classroom or a textbook, the list of strategies that may be applied feeds on a variety of techniques that take into account the way our brain works. These strategies will tell you to turn the conventional teaching approaches upside down, and some of them are so counterintuitive that I’m often tempted to try them.&lt;/p&gt;

&lt;p&gt;However, the technical writer has much more limited wiggle room. And I see one main reason for that: we are usually dealing with a learner who has no time to lose.&lt;/p&gt;

&lt;p&gt;Chances are she has an urgent matter in hands and wishes for a direct answer that simply solves her problem, which makes it hard for us to focus on long-term memory, cognitive load, and other fancy stuff. What the learner expects is words in just the right form and amount to make her perform an action.&lt;/p&gt;

&lt;p&gt;That doesn’t mean we have no room at all to try and get our users through a richer learning experience. But we always need to consider the expected effect. If you’re working on troubleshooting content, go for clarity and avoid experiments.&lt;/p&gt;

&lt;p&gt;But if you’re building a Getting Started tutorial, maybe you can find ways to insert a story, a surprising hands-on experience, or even some humor. It will just take more creativity than usual.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="tech-writing" />
      

      

      
        <summary type="html">I believe that everyone who works with technical writing should read something about instructional design at some point. If not to become an instructional designer, at least to grab a picture of the techniques used to teach adults. After all, in the end of the day that’s what we’re doing.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Hungry lazy users</title>
      
      
      <link href="/2020/02/06/hungry-lazy-users/" rel="alternate" type="text/html" title="Hungry lazy users" />
      
      <published>2020-02-06T00:00:00+00:00</published>
      <updated>2020-02-06T00:00:00+00:00</updated>
      <id>/2020/02/06/hungry-lazy-users</id>
      <content type="html" xml:base="/2020/02/06/hungry-lazy-users/">&lt;p&gt;That cute initialism RTFM (&lt;em&gt;Read The Fucking Manual&lt;/em&gt;) has been around at least since the 80s, which shows that the resistance of users to read documentation is far from recent.&lt;/p&gt;

&lt;p&gt;With the web reaching a maturity phase, however (has it?), the key behavioral component of that scenario shines each time brighter: “people do not search for information with the intellect of a research librarian, but with the nose of a predator”, as Mark Baker nicely said in &lt;a href=&quot;http://everypageispageone.com/&quot;&gt;Every page is page one&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Such exploratory behavior, rather than a linear search for information, resembles the optimal foraging patterns of wild animals, which is why Peter Pirolli named his book &lt;a href=&quot;https://en.wikipedia.org/wiki/Information_foraging&quot;&gt;Information foraging theory&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;It means that whenever a user searches the web for an answer, they will choose a path that brings them the greatest amount of information through the least possible effort.&lt;/p&gt;

&lt;p&gt;So if your website has a whole page with a 15-scrolls wall of text explaining how to use your API but all your user wants is to copy and paste an endpoint, they will probably search Google for it and — after finding the 1-line answer in Stack Overflow — that’s what they’ll go for.&lt;/p&gt;

&lt;p&gt;Using Mark Baker’s terminology, there’s no point in providing &lt;strong&gt;nutritious meal&lt;/strong&gt; if it’s not an &lt;strong&gt;easy catch&lt;/strong&gt;.
Let’s check out a case study.&lt;/p&gt;

&lt;p&gt;Say you are a new GitHub user and you forgot to verify your email address. Now you can’t find the original message, so you need to receive that email once again.&lt;/p&gt;

&lt;p&gt;You could go directly to GitHub Help page, but you’re very likely to try Google first.&lt;/p&gt;

&lt;p&gt;Why? Because we know Google is incredibly good in doing something that &lt;a href=&quot;https://www.amazon.com/Too-Big-Know-Rethinking-Everywhere/dp/0465085962&quot;&gt;David Weinberger&lt;/a&gt; points out as a core feature of the web: “include everything and filter it afterwards”.&lt;/p&gt;

&lt;p&gt;We know Google has (almost) all the information that is. And we know that it will (probably) do a good job in finding what we need in the midst of all that information.&lt;/p&gt;

&lt;p&gt;So, knowing that, let’s take that path — meaning: let’s go for the least effort. You reach Google and enter something like: “resend verification github email”. And this is what it brings you:
&lt;br /&gt;&lt;br /&gt;&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/assets/img/resend-github-verification-email.png&quot; alt=&quot;&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;br /&gt;&lt;/p&gt;

&lt;p&gt;You see that:&lt;/p&gt;
&lt;ol&gt;
  &lt;li&gt;Yes, Google found exactly the information you needed.&lt;/li&gt;
  &lt;li&gt;You don’t even have to scroll down. It’s all there, inside 8 square inches.&lt;/li&gt;
  &lt;li&gt;It’s inside a box. Although there’s more information below, Google is telling you that this box is where you need to look.&lt;/li&gt;
  &lt;li&gt;There’s an image there to help you immediately recognize the position of the button you need.&lt;/li&gt;
  &lt;li&gt;It’s a step-by-step procedure, so you may scan and infer actions rather than read and learn the whole topic.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;So what Google is doing here is realize that:&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;You won’t read; you will scan.&lt;/li&gt;
  &lt;li&gt;If the information is not completely there, you will leave.&lt;/li&gt;
  &lt;li&gt;If the information is not easily catchable, you will search for it elsewhere.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Does it all mean we no longer read books or manuals or even help centers when we have questions about a product?&lt;/p&gt;

&lt;p&gt;Well, if the same answers may be found more easily, yes it does. And that’s good.&lt;/p&gt;

&lt;p&gt;What we need to do is understand there’s no such thing as a linear or hierarchical information path capable of surpassing the hypertextual nature of the web. Whatever bit of information on which the user lands needs to be rich and simple enough for them to stay.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="tech-writing" />
      

      

      
        <summary type="html">'People dont search for information with the intellect of a research librarian, but with the nose of a predator', says Mark Baker in Every Page is Page One .</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">What UX Writing is not</title>
      
      
      <link href="/2020/02/03/what-ux-writing-is-not/" rel="alternate" type="text/html" title="What UX Writing is not" />
      
      <published>2020-02-03T00:00:00+00:00</published>
      <updated>2020-02-03T00:00:00+00:00</updated>
      <id>/2020/02/03/what-ux-writing-is-not</id>
      <content type="html" xml:base="/2020/02/03/what-ux-writing-is-not/">&lt;p&gt;In times of buzzwords colonizing the market and driving people to rethink their careers, I usually find it useful first of all to clear the air by stating precisely what we’re talking about — and, just as important, what it is that we are not talking about.&lt;/p&gt;

&lt;p&gt;The Google Trends chart below shows the growing interest in the term “UX Writing” in recent years — an interest motivated by content professionals who see a new way of contributing more directly to digital product creation.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/assets/img/ux-writing-trend.png&quot; alt=&quot;UX Writing Trends&quot; /&gt;&lt;/p&gt;

&lt;p&gt;But this interest is followed by a great deal of uncertainty.&lt;/p&gt;

&lt;p&gt;In a market where new names come up all the time and where boundaries between areas and competencies change from company to company, content professionals themselves use fluid classifications to define their own work.&lt;/p&gt;

&lt;h2 id=&quot;ux-writing-is-not-content-strategy&quot;&gt;UX Writing is not Content Strategy&lt;/h2&gt;

&lt;p&gt;The first thing UX Writing is not is Content Strategy.&lt;/p&gt;

&lt;p&gt;Content Strategy has a global scope within the company. Among other things, it:&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;Maps all company channels, audiences and messages;&lt;/li&gt;
  &lt;li&gt;Creates standard resources (Content Style Guide, Voice and Tone Guide, Glossary);&lt;/li&gt;
  &lt;li&gt;Ensures that all content manifestations delivered by the company are aligned with the overall strategy.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The UX Writer is responsible for only one of these content manifestations, delivered to the user through the product interface.&lt;/p&gt;

&lt;p&gt;As such, they must follow these standards that are set by the content strategy, just like any other content professional in the company should.&lt;/p&gt;

&lt;h2 id=&quot;ux-writing-is-not-copywriting&quot;&gt;UX Writing is not Copywriting&lt;/h2&gt;

&lt;p&gt;The definition of copywriting can be quite broad, but in the context of companies that develop digital products, when we talk about copywriting we are usually referring to sales-oriented content.&lt;/p&gt;

&lt;p&gt;Its goal is to draw customers. And for that it needs to tell stories, use seductive phrases, be sexy.&lt;/p&gt;

&lt;p&gt;UX Writing, on the other hand, has no commitment to lead attraction.&lt;/p&gt;

&lt;p&gt;Through it, the product communicates with customers who are already part of the base. The goal is no longer to attract but to improve usability. Sexy words usually don’t have much to contribute to that goal.&lt;/p&gt;

&lt;h2 id=&quot;ux-writing-is-not-marketing-copy&quot;&gt;UX Writing is not Marketing Copy&lt;/h2&gt;

&lt;p&gt;I see marketers getting interested in UX Writing — and I think that’s great.&lt;/p&gt;

&lt;p&gt;But it’s important to make one thing clear: Marketing and UX Writing are in quite different battles — and even different battlefields. They should be integrated, of course, but their goals and methods are very distinct.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A UX Writer should be part of the product team.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Just as the developer is responsible for the code and the designer for the experience, the UX Writer must be accountable for the content that the product interface is delivering.&lt;/p&gt;

&lt;p&gt;Once again, she doesn’t want to draw new users. Her goal is to improve the current user experience.&lt;/p&gt;

&lt;h2 id=&quot;so-what-is-ux-writing-then&quot;&gt;So what is UX Writing then?&lt;/h2&gt;

&lt;p&gt;I like the following definition:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;UX Writing is the act of writing copy for product interfaces with the goal of improving user experience.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;It makes it clear that we are talking about product and user experience. Which means:&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;It’s not just any copy. It is copy that appears in the interface of a product;&lt;/li&gt;
  &lt;li&gt;It’s not for any purpose. It aims to improve user experience.&lt;/li&gt;
&lt;/ul&gt;</content>

      
      
      
      
      

      

      
        <category term="ux-writing" />
      

      

      
        <summary type="html">In times of buzzwords colonizing the market and driving people to rethink their careers, I usually find it useful first of all to clear the air by stating precisely what we’re talking about — and, just as important, what it is that we are not talking about.</summary>
      

      
      
    </entry>
  
  
  
    <entry>
      
      <title type="html">Docs are a hard sell</title>
      
      
      <link href="/2020/01/27/docs-are-a-hard-sell/" rel="alternate" type="text/html" title="Docs are a hard sell" />
      
      <published>2020-01-27T00:00:00+00:00</published>
      <updated>2020-01-27T00:00:00+00:00</updated>
      <id>/2020/01/27/docs-are-a-hard-sell</id>
      <content type="html" xml:base="/2020/01/27/docs-are-a-hard-sell/">&lt;p&gt;Yes, documentation is a hard sell, and that might be one of the toughest challenges that lie ahead of a newly born content team.&lt;/p&gt;

&lt;p&gt;In a result-driven environment like the one where every modern company lives, one thing is crutial… yes, you got it: the result. That’s fine, but not when it makes you try to skip the tough parts in order to get there faster. And maintaining a healthy documentation process is indeed a tough part.&lt;/p&gt;

&lt;p&gt;So we often choose to ignore its importance, or at least to lower it as if docs were accessories which we may deal with later.&lt;/p&gt;

&lt;p&gt;One of the reasons is that this result-driven environment values ​​measurable benefits, and measuring the effect of well-done documentation is hard and time-consuming work.&lt;/p&gt;

&lt;p&gt;How happier did your customers become after you changed the titles from gerund to infinitive? What was the reduction in the number of open tickets after you changed the border color of the search button? Hard to tell.&lt;/p&gt;

&lt;p&gt;However, it’s these and many other details that, together, transform a raw and scattered knowledge into the tool that makes your business scalable.&lt;/p&gt;

&lt;p&gt;And the time to pay attention at them is now, when this knowledge is still minimally moldable.&lt;/p&gt;

&lt;p&gt;The effects will not show tomorrow or next week. And maybe when they do show up, the documentation’s influence will not be clear.&lt;/p&gt;

&lt;p&gt;So it may be hard to justify an effort equivalent to that used by the product team to handle the documentation. And, for the most anxious ones, it may be excruciating to wait for numbers while working day after day on commas and buttons and categories names.&lt;/p&gt;

&lt;p&gt;But a product that grows without a well-structured documentation process is like a building that is built with bamboo pillars. At first it may seem possible, but if the product goes far enough, start watching for cracks.&lt;/p&gt;</content>

      
      
      
      
      

      

      
        <category term="tech-writing" />
      

      

      
        <summary type="html">Yes, documentation is a hard sell, and that might be one of the toughest challenges that lie ahead of a newly born content team.</summary>
      

      
      
    </entry>
  
  
</feed>