<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Breno Barreto on Medium]]></title>
        <description><![CDATA[Stories by Breno Barreto on Medium]]></description>
        <link>https://medium.com/@breno.barreto?source=rss-acd96887ddf8------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*jEsTTvkVlYJ52w6oTloBmg.jpeg</url>
            <title>Stories by Breno Barreto on Medium</title>
            <link>https://medium.com/@breno.barreto?source=rss-acd96887ddf8------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 13:15:58 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@breno.barreto/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Building bridges between product and clients with a team of tech writers]]></title>
            <link>https://medium.com/@breno.barreto/building-bridges-between-product-and-clients-with-a-team-of-tech-writers-d950370e71e1?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/d950370e71e1</guid>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[product]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Thu, 18 Jun 2020 17:57:09 GMT</pubDate>
            <atom:updated>2020-06-18T18:03:50.544Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*h1p71f7yFTzCatzzftF3yA.jpeg" /></figure><p>When you think about a software company’s office, perhaps the first image that comes to mind is that of programmers under their hoods, with headphones and dual monitors filled with colorful letters. What you probably don’t realize is that a few chairs away there’s someone who has the word “writer” in the job title — and that the success of the product greatly depends on the result of that person’s work.</p><p><strong>Technical writers</strong> are responsible for creating and maintaining product documentation. Their goal is to transform the use of intrinsically complex software into a simpler experience through content that explains, educates, and solves problems.</p><p>To achieve this goal, the technical writer must combine skills that, for many years, a large part of the market saw as opposite or even self-excluding: they must be able to gather and synthesize complex information and communicate it via text, graphics or video, as a journalist would do; and they must also be able to understand in detail the development and usage of the product, often having to investigate code lines at the same level of depth to which a QA engineer would go, for example.</p><p>I arrived at <a href="https://www.vtex.com/">VTEX</a> in 2016 with the goal of helping to improve the platform’s documentation. At that time, not only did I <em>not</em> consider myself a technical writer — I was not even fully aware that this profession existed, which reflected the general panorama of the market, only then beginning to mature its understanding of what a good documenting process meant. Since then, VTEX consolidated this understanding and created the <strong>Education team</strong>, which today has ten tech writers.</p><h4>In search of references</h4><p>It was exactly during the consolidation of this team that we felt the need to seek references and knowledge about the area of ​​software documentation. Some resources proved to be valuable in helping us to fit our work into a framework of best practices that were kind of globally consolidated. Among these resources was the book <a href="https://www.splunk.com/en_us/blog/splunklife/the-product-is-docs.html">The Product is Docs</a>, written by the Splunk documentation team, and the <a href="https://www.writethedocs.org/">Write The Docs</a> community, which since 2013 has held documentation conferences in several cities in the USA, Europe, and Australia.</p><p>But as valuable as the discovery of these resources was, we also found out that there was still a lot of space to be explored. In particular, we missed publications that went deeper into the intersection of writing and technology and dealt in more detail with the challenges of someone working at that intersection, which applies not only to technical writers but also to UX writers, instructional designers, content strategists, among other roles in the tech industry.</p><h4>The Manu&lt;script&gt;</h4><p>This feeling of void spawned the idea of ​​creating our own publication: in January 2020, we recorded the first interview for <a href="https://anchor.fm/themanuscript"><em>The Manu&lt;script&gt;</em></a>, a biweekly podcast inspired by the desire for knowledge and evolution of the VTEX Education team and produced by two technical writers from that team: Juliana Meyer and myself.</p><p>Eight episodes have been published to date, and each has delved into a specific aspect of writing for technology while opening up new universes that we had never even considered. Among the interviewees, we had: Tom Johnson, a technical writer at Amazon whose blog <a href="https://idratherbewriting.com/">I’d Rather Be Writing</a> is a reference in the area; Mark Baker, author of the book <a href="https://everypageispageone.com/">Every Page is Page One</a>; Mary K. Nielsen, content strategist at Mailchimp; and Torrey Podmajersky, UX writer at Google and author of the bestseller <a href="https://www.oreilly.com/library/view/strategic-writing-for/9781492049388/">Strategic Writing for UX</a>.</p><p>Each interview reinforces how complex the writing job in the technology market can be and also how impactful that job can be on the outcome for companies that really care about it.</p><p>Perhaps one of the interviewees who made this impact most clear was Christopher Gales, Senior Director of Documentation at Splunk. He leads a team of 45 people, including writers, editors, and technical writing managers. In his interview for <em>The Manu&lt;script&gt;</em>, Gales stresses the importance of seeing the professionals responsible for documentation as part of the product team, taking up a role that connects Engineering, Product Management, Design, and Consumer Support.</p><p>“Since the company’s first product leader,” says Gales, “we knew that in order for our customers to adopt the product and be successful with it, at least some of the content consumed by them would need to be built by professional writers.” And to be effective, he says, this must happen from the very beginning of the product development — technical writers must be in the room since the first meeting.</p><p>At Splunk, as well as at VTEX or any other software company, there is knowledge about the product being produced every day. When this knowledge is repressed rather than communicated, it becomes a barrier to the effective use of the product and, consequently, to the company’s commercial success. Technical writers are the professionals capable of understanding, organizing, and transmitting this knowledge, transforming this barrier into a bridge between product and customers.</p><p>I hope more publications such as <em>The Manu&lt;script&gt;</em> are created to multiply this bridge and open new paths for those who work or wish to work in the world of technical writing.</p><p>Listen to <em>The Manu&lt;script&gt;</em> on your favorite platform:</p><ul><li><a href="https://podcasts.apple.com/br/podcast/the-manuscript/id1501843799">Apple Podcasts</a></li><li><a href="https://open.spotify.com/show/3fxF61LYR4BBDAv6YhZV5r">Spotify</a></li><li><a href="https://www.google.com/podcasts?feed=aHR0cHM6Ly9hbmNob3IuZm0vcy8xNDMwOThmMC9wb2RjYXN0L3Jzcw==">Google Podcasts</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d950370e71e1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What UX writing is not]]></title>
            <link>https://uxdesign.cc/what-ux-writing-is-not-d7006a5b4e67?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/d7006a5b4e67</guid>
            <category><![CDATA[design]]></category>
            <category><![CDATA[content-marketing]]></category>
            <category><![CDATA[ux-writing]]></category>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[user-experience]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Thu, 31 Oct 2019 11:08:33 GMT</pubDate>
            <atom:updated>2019-11-07T00:20:57.327Z</atom:updated>
            <content:encoded><![CDATA[<p>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 <strong>not</strong> talking about.</p><p>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.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/793/0*BTUoQjjndQ6ii7Tv" /><figcaption>The rise of the UX Writer</figcaption></figure><p>But this interest is followed by a great deal of uncertainty.</p><p>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.</p><h4>UX Writing is not Content Strategy</h4><p>The first thing UX Writing is not is Content Strategy.</p><p>Content Strategy has a global scope within the company. Among other things, it:</p><ul><li>Maps all company channels, audiences and messages;</li><li>Creates standard resources (Content Style Guide, Voice and Tone Guide, Glossary);</li><li>Ensures that all content manifestations delivered by the company are aligned with the overall strategy.</li></ul><p>The UX Writer is responsible for only one of these content manifestations, delivered to the user through the product interface.</p><p>As such, they must follow these standards that are set by the content strategy, just like any other content professional in the company should.</p><h4>UX Writing is not Copywriting</h4><p>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.</p><p>Its goal is to draw customers. And for that it needs to tell stories, use seductive phrases, be sexy.</p><p>UX Writing, on the other hand, has no commitment to lead attraction.</p><p>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.</p><h4>UX Writing is not Marketing Copy</h4><p>I see marketers getting interested in UX Writing — and I think that’s great.<br>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.</p><p><strong>A UX Writer is a professional who should be part of the product team.</strong></p><p>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.</p><p>Once again, she doesn’t want to draw new users. Her goal is to improve the current user experience.</p><h4>So what is UX Writing then?</h4><p>I like the following definition:</p><blockquote>UX Writing is the act of writing copy for product interfaces with the goal of improving user experience.</blockquote><p>It makes it clear that we are talking about <strong>product</strong> and <strong>user experience</strong>. Which means:</p><ul><li>It’s not just any copy. It is copy that appears in the interface of a product;</li><li>It’s not for any purpose. It aims to improve user experience.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d7006a5b4e67" width="1" height="1" alt=""><hr><p><a href="https://uxdesign.cc/what-ux-writing-is-not-d7006a5b4e67">What UX writing is not</a> was originally published in <a href="https://uxdesign.cc/">UX Collective</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why we insult bots]]></title>
            <link>https://medium.com/@breno.barreto/why-we-insult-bots-438f856bf8a3?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/438f856bf8a3</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[chatbots]]></category>
            <category><![CDATA[bots]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[communications-strategy]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Mon, 04 Feb 2019 18:32:40 GMT</pubDate>
            <atom:updated>2019-02-04T18:32:40.833Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/720/1*PRFhcJBf8_f3d5BfLGjnNg.jpeg" /></figure><p>Westworld, the series produced by HBO, tells the futuristic story of a theme park that simulates the Western and is populated by robots which are almost identical to humans.</p><p>Visitors pay dearly for the tickets with the purpose of living adventures among this robotic population, available for interactions of any kind: sex, murder, torture or whatever else the visitors’ imagination desires.</p><p>Robots believe that everything is real, and their memory is reset every day so they always play the same role again, according to interconnected scripts written by a team of writers.</p><p>Among the possible implications of the series are some reflections of a moral nature:</p><ul><li>If a robot is physically identical to a human being and acts as a human being, is it morally justifiable to treat it (him?) with violence?</li><li>If our interaction with a robot provokes in it the same reactions it would provoke in a human being, even if simulated, then torturing it and killing it remains acceptable?</li><li>To what extent is being conscious different from simulating consciousness?</li></ul><p>We are still far from having robots as evolved as the ones from the series, but not so far from interactions realistic enough to generate in the aggressor the feeling of doing something wrong. In fact, as these interactions become closer to real ones, the user’s brain begins to hide the artificial aspects of its interlocutor.</p><p>Even though we know it is not a human, we personalize the “listener” to make sense of the dialogue, perhaps because it’s less weird to lend a human form to a robot than to put ourselves in the position of someone who talks with a heap of code.</p><p>Think, for example, of a food delivery <strong>chatbot</strong>. It doesn’t make much sense to say “Hi” to this bot, right? “Hi, I would like a yakisoba.” The same result could probably be achieved if you just typed “yakisoba”. And the bot would not be resentful, since rudeness and resentment are concepts devoid of meaning outside of a social context.</p><p>However, it may be that you choose to communicate like this. And if the chatbot responds in the same tone, it is natural that the language codes used in this interaction continue to mirror those used in conversations between humans, using resources whose goal is cordiality and the desire to please, even though a bot can not be pleased or displeased.</p><p>Another revealing fact about interactions with chatbots: whatever their nature, most of the messages they receive miss the purpose of their creation. Bots are often insulted, receive “personal” questions about their age, birthplace, parents’ names, or unusual questions like “How tall is Tom Cruise” or odd requests such as “Sing me a song” or “Tell me a joke”.</p><p>In doing so, the user is <strong>testing the limits</strong> of the chatbot’s simulation ability, in the hopes of finding the edge that surrounds its universe, or with the purpose of being surprised by the size of this universe, not only because of the volume of information, but mainly due to the proficiency in understanding contexts.</p><p>In fact, informal surveys show that failure, materialized for example in information gaps, does more to bring a user closer to the bot than to set them apart, perhaps because it reinforces its similarity with human beings.</p><p>If I ask a food delivery chatbot how many stars the Milky Way has and it gives me an accurate answer, I might be amazed, but that only reinforces its robotic appearance. After all, how many people would have this information on the tip of their tongue?</p><p>But if I tell that same bot that I am sad and it tries to comfort me with a friend-like ease, <strong>the boundaries of this robotic universe begin to dissolve</strong>.</p><p>What happens, then, on the day when those boundaries are far enough to coincide with our own limits?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=438f856bf8a3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What predictive analytics can do for communication]]></title>
            <link>https://medium.com/@breno.barreto/what-predictive-analytics-can-do-for-communication-5924cdd68efc?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/5924cdd68efc</guid>
            <category><![CDATA[metrics]]></category>
            <category><![CDATA[big-data]]></category>
            <category><![CDATA[digital-marketing]]></category>
            <category><![CDATA[marketing-analytics]]></category>
            <category><![CDATA[predictive-analytics]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Fri, 06 Jul 2018 13:43:12 GMT</pubDate>
            <atom:updated>2018-07-06T14:25:37.732Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2HkYo1S3GjABBMTcm4qcTw.jpeg" /></figure><p><strong>Predictive analytics</strong> uses data extracted from the history of a system to build a model capable of predicting the behavior of the same system in the face of new data. That is, it’s an analysis tool to predict future trends.<br> <br>And what can it do for the job of communication professionals?<br> <br>In a comprehensive way, it can assist in decision making and indicate the best paths towards a goal.<br> <br>More specifically, it can, among other things:</p><ul><li>Predict the behavior of interlocutors;</li><li>Identify trending topics and demands;</li><li>Reinforce investment in channels, influencers or media;</li><li>Provide inputs to justify campaigns or approaches;</li><li>Anticipate communication crises or negative reactions;</li><li>Build a proactive relationship with users;</li><li>Improve reach and accuracy of messages.</li></ul><p>Let’s see a simplified example (and obviously not applicable in this format):<br> <br>Let’s say you work at a digital marketing agency responsible for a book publisher communications. Your team needs to roll out a new book launch campaign, and you have access to a set of data from previous campaigns.<br> <br>Looking at such data, you find that relating certain campaign attributes such as number of emails sent to the customer base, budget spent on Facebook ads, duration of promotional videos, it’s possible to build a model that provides insights like this one: each new email sent to customers leads to the sale of ten additional books (please never infer something like this!).<br> <br>So there is a coefficient which represents a fixed correlation between the number of emails sent and the number of books sold. And knowing this, your team can adjust the characteristics of the campaign in order to achieve the best possible result.<br> <br>This type of analysis has existed for decades, but has gained evidence in recent years because we only now have the technology to handle large volumes of data. Big Data has made it possible to create huge data sets comprehensive enough to be statistically relevant.</p><p>Predictive analysis is only one of several aspects of data analysis, and even it can be approached from different angles and through a series of frameworks developed to:</p><ul><li>Understand the problem to be solved;</li><li>Prepare the data set;</li><li>Analyze these data;</li><li>Create a regressive model;</li><li>Validate the model;</li><li>Visually present the results in a friendly way.</li></ul><p>According to each framework, these phases may appear in different formats, but in general this is what it is all about: collecting the data, manipulating it, building a model, applying that model, and displaying the results.<br> <br>There are still few communicators surfing the wave of data analysis, and it’s difficult to tell how much this trend will transform our job.<br> <br>For more traditional markets, such as journalism, its use is still restricted; while for marketers the analysis seems to have more immediate adhesion, having already developed into new segments such as “marketing analytics”.<br> <br>But the fact is that the profession of data analyst has already become one of the most valued at the end of the decade, and its application extends to a multitude of areas, from the most obvious, such as the financial market, to the less ones, such as airlines, which use complex predictive analysis to define tickets price.</p><p><em>Read more on </em><a href="http://techpluscom.com.br/"><em>Tech plus Com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5924cdd68efc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Hungry lazy users]]></title>
            <link>https://uxplanet.org/hungry-lazy-users-2568c3637baa?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/2568c3637baa</guid>
            <category><![CDATA[information-architecture]]></category>
            <category><![CDATA[knowledge-management]]></category>
            <category><![CDATA[content-strategy]]></category>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[ux]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Wed, 03 Jan 2018 17:32:21 GMT</pubDate>
            <atom:updated>2018-01-05T14:39:16.489Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZHENwxZO12XKrcCe9tbB5w.png" /><figcaption>Annie Spratt</figcaption></figure><p>That cute initialism RTFM (<em>Read The Fucking Manual</em>) has been around at least since the 80s, which shows that the resistance of users to read documentation is far from recent.</p><p>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 <a href="http://everypageispageone.com/"><em>Every page is page one</em></a>.</p><p>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 <a href="https://en.wikipedia.org/wiki/Information_foraging"><em>Information foraging theory</em></a>.</p><p>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.</p><p>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.</p><p>Using Mark Baker’s terminology, there’s no point in providing <strong>nutritious meal </strong>if it’s not an <strong>easy catch</strong>.</p><p>Let’s check out a case study.</p><p>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.</p><p>You could go directly to GitHub Help page, but you’re very likely to try Google first.</p><p>Why? Because we know good is incredibly good in doing something that <a href="https://www.amazon.com/Too-Big-Know-Rethinking-Everywhere/dp/0465085962">David Weinberger</a> points out as a core feature of the web: “include everything and filter it afterwards”.</p><p>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.</p><p>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:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/818/1*Qf0_7me5rX_ggS8wiNEcYA.png" /></figure><p>You see that:</p><ol><li>Yes, Google found exactly the information you needed.</li><li>You don’t even have to scroll down. It’s all there, inside 8 square inches.</li><li>It’s inside a box. Although there’s more information below, Google is telling you that this box is where you need to look.</li><li>There’s an image there to help you immediately recognize the position of the button you need.</li><li>It’s a step-by-step procedure, so you may scan and infer actions rather than read and learn the whole topic.</li></ol><p>So what Google is doing here is realize that:</p><ul><li>You won’t read; you will scan.</li><li>If the information is not completely there, you will leave.</li><li>If the information is not easily catchable, you will search for it elsewhere.</li></ul><p>Does all this mean we no longer read books or manuals or even help centers when we have questions about a product?</p><p>Well, if the same answers may be found in an easier way, yes it does. And that’s good.</p><p>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.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fupscri.be%2Fb3e808%3Fas_embed%3Dtrue&amp;dntp=1&amp;display_name=Upscribe&amp;url=https%3A%2F%2Fupscri.be%2Fb3e808%2F&amp;image=http%3A%2F%2Fapi.screenshotlayer.com%2Fapi%2Fcapture%3Faccess_key%3Dfe59908dad3baab69ffab249a2224b03%26viewport%3D1024x612%26width%3D1000%26url%3Dhttps%253A%252F%252Fupscri.be%252Fb3e808%253Fscreenshot&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=upscri" width="800" height="400" frameborder="0" scrolling="no"><a href="https://medium.com/media/96d08ab34921bdd17986cb5c0396842f/href">https://medium.com/media/96d08ab34921bdd17986cb5c0396842f/href</a></iframe><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2568c3637baa" width="1" height="1" alt=""><hr><p><a href="https://uxplanet.org/hungry-lazy-users-2568c3637baa">Hungry lazy users</a> was originally published in <a href="https://uxplanet.org/">UX Planet</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a product mindset in an engineering environment]]></title>
            <link>https://medium.com/@breno.barreto/building-a-product-mindset-in-an-engineering-environment-b9067f21564b?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/b9067f21564b</guid>
            <category><![CDATA[entrepreneurship]]></category>
            <category><![CDATA[startup]]></category>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[project-management]]></category>
            <category><![CDATA[engineering]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Tue, 12 Dec 2017 12:08:26 GMT</pubDate>
            <atom:updated>2018-07-06T13:49:50.071Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pGi466GP1AngU54xJKDBGQ.jpeg" /><figcaption>Marcus Wallis</figcaption></figure><p>Some years ago I helped found a startup whose goal was publishing and delivering books through crowdfunding — when crowdfunding wasn’t as trendy as it is today. Our team of four was made up of three journalists and one engineer. And it struck me as happy news that the engineering specs made so much sense to me. I could relate to them in a way that made me feel closer to the exact sciences, and that eventually turned me into an advocate of every data-based decision.</p><p>A few years after that startup died sadly (and actually after I helped two more startups go bankrupt) I found myself working in a big tech company, where I felt that — despite my journalistic background — I had built quite an exact sciences mindset.</p><p>It didn’t take me long to feel comfortable among engineers and their buzzwords. It was actually invigorating to be pushed towards the need to learn new technical stuff such as JavaScript, API requests and React. I wanted to suck as much technical knowledge in as I could.</p><p>That made me feel more at home, which was awesome — but not that useful. I felt that the amount of effort I put in learning to code, for example, didn’t really pay off as fastly as expected. I began to feel like I was pushing myself towards the path of a young engineer trying to get a job at the tech industry. Which would be great — if I was a young engineer trying to get a job at the tech industry. I already had a job, and it required other types of skill.</p><p>And then came the next revelation (for me; I know this is quite standard talk for PMs but that was all new for me, so take it easy).</p><p><em>Understanding the engineers’ mindset is useful as long as you can filter it through a product mindset.</em></p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fgiphy.com%2Fembed%2FV0IdVIIW1y5d6%2Ftwitter%2Fiframe&amp;display_name=Giphy&amp;url=https%3A%2F%2Fmedia.giphy.com%2Fmedia%2FV0IdVIIW1y5d6%2Fgiphy.gif&amp;image=https%3A%2F%2Fi.giphy.com%2Fmedia%2FV0IdVIIW1y5d6%2Fgiphy.gif&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=giphy" width="435" height="435" frameborder="0" scrolling="no"><a href="https://medium.com/media/8bdefc7b87f1eae195d6bb520640a6c6/href">https://medium.com/media/8bdefc7b87f1eae195d6bb520640a6c6/href</a></iframe><p>So whenever I needed to ask an engineer something, or whenever an engineer asked me something, I started making myself the following questions:</p><ul><li>What is the benefit for <strong>the user</strong>?</li><li>What is the impact on <strong>the user</strong>?</li><li>How does this make life better or worse for <strong>the user</strong>?</li><li>What does <strong>the user</strong> think of it?</li></ul><p>Having given focus to that beloved entity (<em>the user</em>) I realized where to find the real impact of my job — and for that matter of everyone’s jobs.</p><p>But how does one filter the engineers’ mindset in order to achieve the product’s actual goals?</p><p>Well, it seems to me that this becomes easier in companies that are already driven by a product mindset.</p><p>If that’s your case, just ask yourself a lot of “whys” before moving on to the next epic or story or hot fix. Why creating that new section in the website? Why do users want it? Why will it make their life better?</p><p>But if your company is not driven by a product mindset, then you might need to head a daily battle on behalf of the user. Instead of only reminding yourself of the importance of doing things with the right purpose during weekly meetings, you’ll need to remind those around you — all the time.</p><p>Whenever an engineer presents arguments to refactor the entire code, ask them what the impact on the user will be; how many more users will come; how happier they will become; what they will lose during the time your team is not doing something else.</p><p>Whenever a new hire or strategy or roadmap change is presented, raise your user flag and ask why.</p><p><em>Read more on </em><a href="http://techpluscom.com.br/"><em>Tech plus Com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b9067f21564b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Expanding content with the right focus]]></title>
            <link>https://medium.com/@breno.barreto/expanding-content-with-the-right-focus-9114b4e79c05?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/9114b4e79c05</guid>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[information-architecture]]></category>
            <category><![CDATA[content-strategy]]></category>
            <category><![CDATA[content]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Tue, 05 Dec 2017 13:09:32 GMT</pubDate>
            <atom:updated>2018-07-06T13:50:25.911Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sjet9qSO4O8fX2-FXvxflw.jpeg" /><figcaption>Mikito Tateisi</figcaption></figure><p>About six months ago my team was faced with the challenge of organizing the company’s knowledge base. At that time, what lay ahead of us was a five hundred and few articles legacy, each of them in three different languages — English, Portuguese and Spanish. And our goal was to catalog such knowledge so that it would be feasible to maintain it and expand it in a structured way.</p><p>I had already been concentrating on all that content for a few months, but — as much as I tackled it from different angles — some fundamental doubts remained.</p><p>I felt comfortable to improve articles individually, or to judge the quality of the overall documentation. But it soon became clear that, without having tidied things up — that is, without having answered those fundamental doubts — neither the greatest editing effort nor the best editorial judgment would make a significant difference.</p><p>These doubts were simple, but the answers were the key to building the dynamic, detailed picture we needed:</p><ul><li>How updated is each translation of each article in our database?</li><li>To what extent does the support team use our articles to answer customers?</li><li>What is the percentage of customer questions for which there are no articles in response?</li><li>What is the scope of knowledge currently covered by our database?</li><li>What is the total scope of knowledge we need to offer?</li><li>Where are the answers that can turn into articles capable of covering the gap between offered and needed knowledge?</li></ul><p>1. Versioning</p><p>The effort to organize our knowledge base began in the most obvious way: a spreadsheet with the list of articles we had in Contentful, the CMS we’ve been using for some time now.</p><p>And right away came the initial challenge: how to control the translation stage of each of these articles?</p><p>Since anyone in the company can edit or create articles (something we consider crucial to keep the knowledge base scalable and valuable), an article could be born in Portuguese and English, but remain months without being translated to Spanish; or it could be born in the three languages, but only be edited in its Portuguese translation, leaving the English and Spanish versions behind.</p><p>To control these changes in a universe of hundreds of articles through a spreadsheet without going crazy, we needed a process as smooth as possible.</p><p>That was when we borrowed the instructional design concepts of learning object and knowledge object (with a great deal of poetic license).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/157/1*zYENTiHBEh2ra8XkpOzQAQ.png" /><figcaption>For each KO an objective; for each LO 3 language versions</figcaption></figure><p>We started calling each learning object an article. And we considered each of these learning objects as an entity made up of different knowledge objects.</p><p>That is, a learning object was a piece of learning material, something deliverable to the user. It was the molecule, made up of different atoms of knowledge (the knowledge objects).</p><p>When something on our platform changed, we updated the date of the corresponding knowledge object, which triggered a necessary change in its translations.</p><p>Confusing? Yes, a little. But maintaining this structure proved even more confusing, as the spreadsheet that we finally set up makes clear:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mfErtdq6wsy77i8jAbWKMQ.png" /><figcaption>Too much to control</figcaption></figure><p>We built this conceptual structure mainly because of our translation problem. We needed to clearly differentiate a change in translation (a typo, for example) from a change in the knowledge itself (something new on the platform or in the company).</p><p>But that meant with each change we lost several minutes just to update our control system, because a single change involved too many concepts and entities of different nature.</p><p>So we realized we needed to simplify the whole thing.</p><p>Instead of considering the knowledge object as a separate entity, we came to see the most up-to-date translation as the correct knowledge itself, which should serve as a reference.</p><p>In addition, we stopped using dates as reference and moved to the concept of version. Thus, for an article that had suffered, for example, five consecutive changes in English, it mattered little the dates of those changes. The article was a version ahead of its translations in Portuguese and Spanish, and that was all.</p><p>The takeaway came from the formula that made clear which action we needed to take for every article:</p><ul><li>Same version in all languages: <em>no action</em>.</li><li>Non-existent article in all languages: <em>creation</em>.</li><li>Change in platform (version becomes zeroed): <em>fix</em>.</li><li>One or more languages ​​in different versions: <em>update</em>.</li><li>Non-existent article in some language: <em>translation</em>.</li><li>Different translations, without clarity of which is the last one: <em>merge</em>.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2fPwe7mM5UTjvulBIQm46g.png" /><figcaption>For each article a precise due action</figcaption></figure><p>2. Support metrics</p><p>The second stage was related to metrics, especially those coming from customer support. This is because it’s in this team that lives the greatest pain caused by the inefficiency of documentation.</p><p><em>Poor or hard to find documentation = more tickets = more work for the support team = more money spent by the company</em></p><p>So we needed to know the evolution of the articles usage by the support team in order to answer questions from customers:</p><ul><li>How is the percentage of tickets answered with documentation evolving?</li><li>How is the percentage of tickets for which there was no documentation evolving?</li><li>How is the percentage of tickets answered with incomplete documentation evolving?</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/587/1*kjcDZqemPyCiO_Xb8PMz4Q.png" /><figcaption>Self-service score evolution</figcaption></figure><p>In the first month, the numbers didn’t say much, but with the evolution of this metric we began to have a clearer idea of ​​where we were heading. Was the documentation becoming more efficient, less efficient or was it stable?</p><p>And to further clarify the meaning of such “efficiency,” we decided to try a kind of metrics used by Zendesk: the <em>self-service score</em>. It takes the number of unique users from the knowledge base and divides it by the number of unique users who opened tickets in the same period, in order to measure exactly what we wanted: the “conversion” rate of the documentation.</p><p>In other words, with that number we wanted to know precisely how many users of the knowledge base were required for a ticket to be opened. Obviously, the smaller that number, the worse.</p><p>3. The answer is in the ticket (literally)</p><p>OK, now we had a much better understanding of the health of our articles and the efficiency of the documentation. But this was a picture of what we already had in our hands. In order to make the metrics move, we needed to identify the size of the gap still to be filled by the documentation, as well as the issues to be addressed by our team.</p><p>The answer to these questions was harder to get — and we’re actually still trying to make it clearer.</p><p>Part of it is in the use of documentation itself: by observing and measuring how our users search for content, we get the chance to identify most searched terms, inefficient articles, poorly explored categories, and so on.</p><p>Another part — and one that is currently more present in our daily job — is in the tickets answered by the support team. After all, every response given by one of our agents, if not documented, is a missed opportunity of adding knowledge to our base.</p><p>While using Zendesk to interact with clients, our agents are required to flag tickets as answered “with documentation”, “without documentation” or with “incomplete documentation”. Then, using Zapier, we make each new ticket closed without or with incomplete documentation to enter a Google Sheets queue.</p><p>That queue is our gold mine: each line represents a question from a customer that the documentation was not able to answer — that is, it represents an opportunity to improve documentation and avoid new tickets concerning that same issue.</p><p><em>Read more on </em><a href="http://techpluscom.com.br/"><em>Tech plus Com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9114b4e79c05" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The next best content strategy]]></title>
            <link>https://medium.com/@breno.barreto/the-next-best-content-strategy-d9fa3627eb13?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/d9fa3627eb13</guid>
            <category><![CDATA[email-marketing]]></category>
            <category><![CDATA[content-strategy]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Tue, 26 Sep 2017 21:42:26 GMT</pubDate>
            <atom:updated>2018-07-06T13:50:43.021Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gOnXXgHe8En4jtmZu1TN4Q.jpeg" /></figure><p>It’s funny like every great idea related to content seems old after a few months of repetition. Take something like sender’s name standards for email marketing. If, like me, you receive a lot of emails from startups and tech solution companies, you’ve been probably seing many of them in the format <em>{First Name} from {Company}</em> for quite some time now.</p><p>Using your (or someone else’s) first name in the sender field is a strategy that brings informality and personification to the contact with your client. It is indeed a very good idea. But now seeing my email box filled with Johns and Marys and Peters from all those cool companies kind of makes me a little uncomfortable.</p><p>Suddenly it doesn’t feel natural anymore. The repetition broke the spell and made the strategy more evident than its intended effect (at least for my eyes, which are obviously more trained than the average).</p><p>As soon as I finish typing this text, I’ll go send an announcement for our clients base, and the sender will probably be “Breno from VTEX”, which will make me feel bad for not having found the next best strategy for that task.</p><p><em>Read more on </em><a href="http://techpluscom.com.br/"><em>Tech plus Com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d9fa3627eb13" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Clarity vs friction in technical writing]]></title>
            <link>https://medium.com/@breno.barreto/clarity-vs-friction-in-technical-writing-3faaf9f114b6?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/3faaf9f114b6</guid>
            <category><![CDATA[instructional-design]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[elearning]]></category>
            <category><![CDATA[information-architecture]]></category>
            <category><![CDATA[technical-writing]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Wed, 20 Sep 2017 23:04:54 GMT</pubDate>
            <atom:updated>2018-07-06T13:51:00.280Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/626/1*R-yD6ZX5Vb6O_Y3LhyOR0g.jpeg" /></figure><p>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.</p><p>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.</p><p>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.</p><p>Some of the ways in which such friction may be created, according to the author of <em>Design for how people learn</em>, are:</p><ul><li>Tell stories;</li><li>Surprise the learner;</li><li>Create social interaction;</li><li>Show the learner “shiny things”;</li><li>Make the learner explain the subject.</li></ul><p>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?</p><p>I believe it is, but only to a certain point.</p><p>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.</p><p>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.</p><p>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.</p><p>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.</p><p>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.</p><p><em>Read more on </em><a href="http://techpluscom.com.br/"><em>Tech plus Com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3faaf9f114b6" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Docs are a hard sell]]></title>
            <link>https://medium.com/@breno.barreto/docs-are-a-hard-sell-c32176090fc?source=rss-acd96887ddf8------2</link>
            <guid isPermaLink="false">https://medium.com/p/c32176090fc</guid>
            <category><![CDATA[content-strategy]]></category>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[ux-writing]]></category>
            <category><![CDATA[product-management]]></category>
            <dc:creator><![CDATA[Breno Barreto]]></dc:creator>
            <pubDate>Mon, 11 Sep 2017 22:35:18 GMT</pubDate>
            <atom:updated>2018-07-06T13:51:19.222Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Y9x2cTy2QhXcEzwZ2xieaQ.jpeg" /><figcaption><a href="http://www.freepik.com/cornecoba">cornecoba / Freepik</a></figcaption></figure><p>Yes, documentation is a hard sell, and that might be one of the toughest challenges that lie ahead of a newly born content team.</p><p>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 <em>get there faster</em>. And maintaining a healthy documentation process is indeed a tough part.</p><p>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.</p><p>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.</p><p>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.</p><p>However, it’s these and many other details that, together, transform a raw and scattered knowledge into the tool that makes your business scalable.</p><p>And the time to pay attention at them is now, when this knowledge is still minimally moldable.</p><p>The effects will not show tomorrow or next week. And maybe when they do show up, the documentation’s influence will not be clear.</p><p>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.</p><p>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.</p><p><em>Read more on </em><a href="http://techpluscom.com.br/"><em>Tech plus Com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c32176090fc" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>