<?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 Antti Hietala on Medium]]></title>
        <description><![CDATA[Stories by Antti Hietala on Medium]]></description>
        <link>https://medium.com/@AnttiHietala?source=rss-5d934ed5da4e------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*Vx6la41jzRDFpuhC-6asfg.jpeg</url>
            <title>Stories by Antti Hietala on Medium</title>
            <link>https://medium.com/@AnttiHietala?source=rss-5d934ed5da4e------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 02:13:48 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@AnttiHietala/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[Jump over these obstacles to website personalization]]></title>
            <link>https://medium.com/@AnttiHietala/jump-over-these-obstacles-to-website-personalization-ca1628e96cd1?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/ca1628e96cd1</guid>
            <category><![CDATA[business]]></category>
            <category><![CDATA[digital-marketing]]></category>
            <category><![CDATA[motivation]]></category>
            <category><![CDATA[marketing]]></category>
            <category><![CDATA[content-marketing]]></category>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 16 May 2017 11:39:03 GMT</pubDate>
            <atom:updated>2017-05-16T11:39:03.315Z</atom:updated>
            <content:encoded><![CDATA[<p>What do you think are the primary obstacles that prevent companies from personalizing their website?</p><ul><li>Unproven ROI?</li><li>Don’t know who to target?</li><li>Tools are difficult to use?</li></ul><p>Nope. Those were my guesses but they all proved wrong.</p><h3>“We haven’t managed to get started”</h3><p>In 2016 we interviewed 50 <a href="https://www.magnolia-cms.com/customers.html">Magnolia clients and partners</a> to find out what was important to them. One topic raised consistently throughout the conversations was the need to personalize web content. Strong validation on that point. Almost everyone said they <strong>wanted</strong> to do personalization but <strong>had not managed to get started yet</strong>.</p><p>We were curious as to why. What was holding them back?</p><p>These companies are no strangers to running a successful business on the web — quite the opposite. They are web-savvy firms that see value in personalization. Broadly speaking everyone agrees that even basic web personalization can give a higher return on investment (ROI) than other, more traditional, marketing programs (<a href="http://www.mckinsey.com/business-functions/marketing-and-sales/our-insights/the-demands-of-on-demand-marketing">McKinsey 2013</a> summarizes it nicely).</p><p>Not knowing who to target was not a key obstacle either. Everyone used Google Analytics to analyze visitor patterns. Google conveniently groups the visitors into segments like New users and Returning users and provides plenty of ideas how to segment your visitors further. Once you have GA, it’s not a leap of imagination to run an A/B test in <a href="https://www.google.com/analytics/optimize/features/">Google Optimize</a> — change a little something and see if it performs better.</p><p>The same visitor segments can be used for targeting:</p><blockquote>You can also use segments as the basis for audiences. For example, you might create a segment of users who visit your menswear pages, and then target just those users (your audience) with a remarketing campaign. <br>— Google Analytics Help: <a href="https://support.google.com/analytics/answer/3123951?hl=en">About segments</a></blockquote><p>In addition to Google Analytics data, companies typically have their own marketing automation and CRM systems that hold even more valuable information about customers such as who had bought what and when.</p><p>Getting started was blocked by something else.</p><h3>1. Fear of having to create new content</h3><p>There’s a persistent misunderstanding that in order to serve personalized content you need to create new content. Even seasoned pros in the content management industry sometimes fall victim to this fallacy.</p><p>It is patently false. You don’t need new content. You can <strong>substitute</strong> existing content items.</p><p>Let’s take a concrete example:</p><blockquote>You stay at a hotel and have a gin &amp; tonic from the minibar. The hotel staff records your drink preference. The next time you book they put gin and tonic in the minibar before your arrival.</blockquote><blockquote>The hotel doesn’t invent a new drink. They don’t distill a new batch of gin from scratch. They have literally hundreds of cans of gin and tonic sitting in a storage room next to hundreds of other drinks.</blockquote><blockquote>Rather than stocking the minibar with a random sampling of drinks they put gin and tonic front and center. They <strong>substitute</strong> one thing for another to make the experience more relevant to you.</blockquote><p>Now transport that idea to web content management. You likely already have some content that is more relevant to the visitor than other content. Put the relevant content first.</p><p>I wrote about this common misunderstanding in <a href="https://medium.com/@AnttiHietala/five-reasons-to-personalize-1ee29fd3c218">Five reasons to personalize</a> and offered modular content as a solution. It’s a good idea to organize your core content into small, reusable chunks and keep them away from the editorial (supporting) web content of your site. The pool of reusable content items is now at your disposal. You can assemble sets of items and target them to the visitor according to his or her preference.</p><p>Flagship brands on the web do exactly the same:</p><ul><li>Airbnb hosts don’t write unique home descriptions for each visitor segment. The descriptions are the same for everyone. Instead, based on your location and prior rentals Airbnb assembles a set of homes that fit your taste.</li><li>Amazon doesn’t rewrite product descriptions for each segment either. From a pool of millions of products they assemble a set of existing items that we might like.</li><li><a href="https://www.magnolia-cms.com/customers/customer-stories/alior.html">Alior Bank</a> has a pool of financial products. The pool is much smaller than Airbnb and Amazon’s, yet some of the products match the needs and circumstances of the visitor better than others. Student? Starting a family? Retiring? From a pool of content items the bank assembles product suggestions for your particular life situation.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PydRZJySRyljO0PJiwyQvQ.png" /><figcaption>Avis: <a href="https://www.avis.ch/en/car-hire-offers/switzerland-offers">Switzerland Car Hire Offers</a></figcaption></figure><h3>2. Analysis paralysis</h3><p>The other great stumbling block is overanalyzing the situation.</p><p>It usually goes like this: consult everyone in the organization, analyze the target audience, create 21 different personas to represent archetypal visitors, state ambitious goals such as “personalize anything anytime”, and then freeze because the plan is so big and complex that you don’t know how to proceed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*N4sqk51hzxLpaGnODgirtw.png" /><figcaption>Big Content Alliance: <a href="https://www.slideshare.net/BigContentAlliance/bca-personalization-content-strategy-press-pause-to-get-it-right/29">Personalization Content Strategy</a></figcaption></figure><p>It’s better to start small. Create the first little experiment. Change the color of a button in a call to action. See if visitors sign up for your newsletter more often when the button is green.</p><p>It may be an insignificant change but that’s the key: the effort was also insignificant. The experiment is running. Exciting!</p><p>Then change something bigger. You have client references or customer logos, right? Instead of listing all the customers, how about showing only five customers while making sure they are from the same country as the visitor? You are not creating any new content, just choosing a subset of existing content that is relevant for the visitor.</p><p>A professional content strategist might object to such spontaneous tomfoolery. They might argue that creating targeted content variations for personalization can be quite substantial effort — and overwhelming for some — adding that a carefully defined content strategy can provide the process and guidelines necessary to get there.</p><p>Yes, sure. It’s possible that your experiment does not yield meaningful results. But you only invested an hour and already have an idea on what to change next.</p><p>To summarize:</p><ul><li>You don’t need to create more content. Just be smarter with how you use existing content.</li><li>Don’t get stuck in analysis paralysis. Start with simple personalization experiments.</li></ul><p>Surprise your visitors and yourself what you can do with little things.</p><p><a href="https://www.magnolia-cms.com/magnolia-resources/magnolia-library/personalization-landing-page.html">Get your free guide to personalization</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ca1628e96cd1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Five reasons to personalize]]></title>
            <link>https://medium.com/@AnttiHietala/five-reasons-to-personalize-1ee29fd3c218?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/1ee29fd3c218</guid>
            <category><![CDATA[social-media-marketing]]></category>
            <category><![CDATA[personalization]]></category>
            <category><![CDATA[marketing]]></category>
            <category><![CDATA[content-marketing]]></category>
            <category><![CDATA[big-data]]></category>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 13 Sep 2016 06:42:22 GMT</pubDate>
            <atom:updated>2016-09-13T14:22:45.834Z</atom:updated>
            <content:encoded><![CDATA[<h4>This post explains <strong>why</strong> it makes sense to start personalizing your website now.</h4><h3>Personalization is mainstream</h3><p>The days of mass marketing will soon be over. Serving the same web content to everyone has run its course. As visitors, we expect content to be <strong>relevant</strong> to us.</p><p>Personalization turns the old one-to-many broadcasting model on its head: a personalized website adapts its content to the visitor according to his or her personal preferences and needs. Personalized content is more relevant and meaningful than any vanilla variety.</p><p>The goal is to build a <em>relationship</em> in which the visitor indicates their interest and the website serves matching content. Of all possible content variants that could be offered, personalization finds the one that fits best.</p><p>While I worked on <a href="https://documentation.magnolia-cms.com/display/DOCS/Component+personalization">component personalization</a> for Magnolia I spoke with clients from travel to telecom, with partners and agencies, with authors and developers. Web content professionals agree that personalization has moved beyond the hype into mainstream and is finally starting to produce returns.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/904/1*rGQGGuYeSMb2Cc-mfn83eQ.png" /><figcaption><a href="http://www.gartner.com/smarterwithgartner/five-key-trends-in-gartners-2015-digital-marketing-hype-cycle/">Gartner Digital Marketing Hype Cycle 2015</a></figcaption></figure><h3>Relevance</h3><p>Frankly, it’s inconsiderate to serve irrelevant or redundant web content to visitors today for two reasons:</p><ul><li><strong>Personalization tools are widely available.</strong> Pick any major CMS (content management system) and you will find personalization features. You can target content to visitors by channel, device, location, date, demographics, past behavior and preference. Sure, the first attempts at delivering personalization tools fell rather short on user friendliness. But many have matured since then. At Magnolia, we saw a need for marketers to get their hands on tools that let them focus on the task instead of running down to IT to get support. Ideal personalization tools require no developer involvement beyond the initial setup of targeting attributes. This means that authors can produce, manage and target content <em>on their own</em>.</li><li><strong>There is a wealth of data about visitors.</strong> As consumers, our actions are <a href="http://www.ibmbigdatahub.com/blog/big-datastillery-strategies-accelerate-return-digital-data">recorded at every opportunity. Our social graph is mapped in detail</a>. So much is known about our preferences that, as consumers, we start to see un-personalized content as noise. Irrelevant offers stick out. “Why would you even suggest that?” Producing and maintaining content that misses the mark costs money. It’s advertising dollars thrown to the wind.</li></ul><p>There is, however, one valid excuse for not personalizing content to every visitor: <strong>scale</strong>.</p><blockquote>“The hardest part of the business is how you create content at scale while making it relevant.” — Brian Harrington, Zipcar</blockquote><p>On one hand, content needs to be tailored to the visitor. On the other, it needs to be reusable, otherwise production won’t scale up. This is quite a conundrum. <a href="http://www.forbes.com/forbesinsights/pwc_content/index.html">According to Forbes</a>, marketers will not be able to write or spend their way out of this problem.</p><p>If you look at scalability as a content <strong>production</strong> problem, indeed there is no obvious way out. Producing creative, relevant content takes time. While <a href="https://automatedinsights.com/case_studies.html#e-commerce">natural language generation</a> software can produce human-sounding narrative from product data you need a large volume of comparable products with similar properties for NLG to be more efficient than human authors. Consumers are also rather sensitive to mechanical, repetitive language — they can sniff it out.</p><p>However, if you look at scalability as a content <strong>management</strong> problem there are solutions.</p><ul><li><strong>Modular</strong> content is one. Create reusable content blocks that can be reassembled to meet personalization needs. This approach, also known as <em>content pool</em> or <em>content hub</em>, assumes that content lives in a system that is capable of managing pools of structured, reusable content elements. Importantly, the content is not stored on web pages. It is completely independent of presentation and channel. (“There is no page” should be the subject of another blog post.)</li><li><strong>Tagging</strong> is another. You probably have relevant content on your site but it is not categorized for findability and reuse. Apply tags that match desired visitor attributes. A travel website might tag their tours as <em>active</em>, <em>cultural</em> or <em>family</em>. A sensible, human-readable taxonomy is a great place to start because it allows you to experiment with personalization manually first. Step into the visitor’s shoes and preview the digital experience to make sure it makes sense. Eventually you can hand the targeting job to an AI. Matching tags to visitors is a hopelessly boring task. Perfect job for a <a href="https://blogs.oracle.com/atgstrategy/entry/personalization_fundamentals_part_2_rules">rule engine</a>.</li></ul><h3>Individuals vs. segments</h3><p>Today, marketers need to reach <strong>audiences-of-one</strong>. Individuals like you and me. Each of us different with unique goals and needs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*OvAjm-WprcgEIStpt-ce2w.jpeg" /></figure><p>While segmenting an audience into homogenic groups (visitors from Europe, visitors interested in technology, visitors with red hair) is a perfectly valid approach to understanding who your visitors are, segments still lump many visitors into the same bucket. Today, consumers expect content that is relevant for them as an individual.</p><p>A travel company client I work with stores the visitor’s holiday search terms in a cookie: destination, travel dates, number of adults, number of kids and so on. As the visitor looks for the perfect holiday the site keeps appending each new search into the cookie. With a detailed search history the company can draw a more reliable picture of what type of travel the visitor is interested in. It’s hyper-specific in a thoughtful way.</p><p>Compiling searches over time also helps the travel company avoid jumping to conclusions. If a visitor searches for a holiday in Orlando once they could be doing it as a favor for a friend or just out of curiosity. However, if the search becomes a more frequent pattern it’s more likely the user is genuinely interested in the destination and offering personalized content will pay off.</p><h3>Thoughtful remembrance</h3><blockquote>Engage customers! Build loyalty!</blockquote><p>That’s how personalization is sold to marketers. Unfortunately, engagement and loyalty are marketing buzzwords that are hard to express in concrete terms. Let’s replace the boilerplate text with goals you can realistically achieve with personalization.</p><p>No customer wishes to be “engaged”. Customers want services and products that are thoughtful and relevant. They may want to be occasionally delighted with creative copy, and for the rest of the time be left alone.</p><blockquote>We do not wish to be “engaged.” The belief that we do is just one example of the industry smoking its own exhaust. — Doc Searls, <a href="http://doc.blog/2016/09/06/dearAdvertisingWeAreNotAnAudience.html">Dear Advertising, We are not an “audience”</a></blockquote><p>Even the most admired digital marketing companies in the world are still learning the difference between engagement and repetition. Our attempts at engagement frequently end up as woefully misguided bombardment with identical offerings because as marketers we confuse engagement with repetition.</p><h3>Rex Rizzo on Twitter</h3><p>Wired: &quot;Machine learning will TAKE OVER THE WORLD!&quot; Amazon: &quot;We see you bought a wallet. Would you like to buy ANOTHER WALLET?</p><p>I propose replacing engagement with <a href="http://blog.hubspot.com/marketing/8-personalization-trends-that-are-reinventing-the-buyers-journey">Dan Stasiewski</a>’s term <strong>thoughtful remembrance</strong>.</p><blockquote>Customer loyalty results when a brand can form a relationship with the buyer through acts of thoughtful remembrance. For example, knowing their preferences, respecting the customer, not rushing them toward a desired action.</blockquote><p>Examples where personalization can you help remember the visitor:</p><ul><li>Recover abandoned shopping carts by reminding the visitor where they left off, even as they return to the site after a few days.</li><li>Upsell the next level product or service since you know what the user currently holds.</li><li>Suggest a relevant local event based on a purchase.</li></ul><p>These are all thoughtful acts, respectful to the customer and as such more likely to elicit a positive reaction to your brand and your personalization attempts.</p><h3>Customer journey</h3><p>There is no such thing as instant loyalty. Loyalty must be earned over time. The idea that we can lure the customer back to the site by amplifying the message is just ludicrous.</p><p>According to <a href="https://blogs.adobe.com/digitaleurope/web-analytics/big-data-analytics-global-marketing-strategy/">Adobe</a>, the average consumer goes through a minimum of five touch points with a business before converting. Such a long customer journey needs careful design to make each touchpoint part of a consistent digital experience.</p><p>The HubSpot <a href="http://www.hubspot.com/inbound-marketing">inbound marketing model</a> is a great illustration of the customer journey. At each stage of the journey, you can personalize content to the needs and wants of the customer. Content should get narrower, more focused, and more relevant as the visitor moves to the right.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/792/1*LDSote3Un1vF4uVWAce1lw.png" /><figcaption><a href="http://www.hubspot.com/inbound-marketing">HubSpot Inbound Methodology</a></figcaption></figure><p>Some examples how personalization can help at each stage:</p><ul><li><strong>Attract</strong>: Acknowledge and greet visitors who come from your social media posts. You know which campaign they came from since you set it up. Try serving some referral-specific content, even just “Hi Facebook user!”.</li><li><strong>Convert</strong>: Create a personalized call-to-action at the end of a blog post. At this point you already know the reader is interested and aware of your offering.</li><li><strong>Close</strong>: Include the first name of the recipient in an email to boost the click-through rate.</li><li><strong>Delight</strong>: Personalize your home page for returning customers. In the US, 40% of revenue comes from returning or repeat purchasers, who represent only 8% of all visitors. (<a href="http://success.adobe.com/assets/en/downloads/whitepaper/13926.digital_index_loyal_shoppers_report.pdf">Forrester</a>)</li></ul><p>One customer journey toward one conversion or long-term brand preference.</p><p><em>Antti Hietala is a product manager at </em><a href="https://www.magnolia-cms.com/"><em>Magnolia</em></a><em>. Tasked with articulating Magnolia’s value proposition, he stays in constant contact with users and feeds the product roadmap with front-line input. </em><a href="https://twitter.com/antarctic74"><em>@antarctic74</em></a></p><h3>More by the author</h3><ul><li><a href="https://medium.com/technical-documentation/why-i-dont-do-epub-1573472c9236">Why I Don’t Do EPUB</a></li><li><a href="https://medium.com/technical-documentation/custom-content-apps-a1fad42422df">Custom Content Apps</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1ee29fd3c218" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Road mapping Magnolia]]></title>
            <link>https://medium.com/@AnttiHietala/road-mapping-magnolia-2d5c064bc801?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/2d5c064bc801</guid>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[content-management]]></category>
            <category><![CDATA[roadmaps]]></category>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Mon, 04 Jan 2016 09:44:47 GMT</pubDate>
            <atom:updated>2016-01-04T09:44:47.866Z</atom:updated>
            <content:encoded><![CDATA[<p>What is the best way to collect requirements for a product roadmap? What sources should you listen to? Which items should you work on?</p><p>In this post I explain how we created the current <a href="https://wiki.magnolia-cms.com/display/DEV/Roadmap">Magnolia roadmap</a>. The information sources we used may also work for you. I have also included a mind mapping exercise that can be used to elicit requirements. It works really well in small teams.</p><h4>Sources for requirements</h4><p>Product planning should take everybody’s input into account. Cast a wide net. Talk to as many users as you can. Only then start narrowing down what you will actually implement.</p><p>In the latest round of Magnolia feature planning we collected requirements from three sources:</p><ol><li><strong>Client survey</strong>. Every few years we do an extensive client survey. In 2015 we asked users what trends they see in the industry and what they like and don’t like in the product. 621 people answered, which is a great result, a treasure trove of educated opinions. We itemized the feedback and gave extra weight to any items that were mentioned repeatedly.</li><li><strong>Team input</strong>. We interviewed all internal Magnolia teams from product development to sales. What features would they like to see in the next major release? What is important to fix first? We used mind mapping to elicit and document the teams’ requirements, see the exercise below if you want to try.</li><li><strong>UX top 10</strong>. For more than a year we have collected major user experience pain points reported by users, customers and partners. Our goal is to fix them in an initiative titled “Magnolia is a joy to use”. We consider UX so important that a full third of items on the current roadmap are user experience improvements.</li></ol><p>Once we had requirements from these three sources in a spreadsheet we started looking for a common theme. Many items had something to do with <strong>author experience</strong>, making authors’ lives easier. So we chose it as a theme for the current roadmap.</p><h4>Exercise: Mind mapping roadmap input</h4><p>Mind mapping is a great technique for collecting requirements from teams of under 10 people. The mind mapping session is personal and immediate. The participants feel that their concerns are heard and they feel invested in the roadmap.</p><ol><li>Invite each team in your organization to a road mapping exercise.</li><li>Ask the team members to name features, fixes and enhancements they would most like to see in the product. Think big, blue sky! Draw the features on a mind map on the wall.</li><li>Once all items are drawn, give everyone 3 stickers. Ask them to vote the most important items.</li><li>Identify trends by circling the most voted topics. These are your strongest candidates for the roadmap.</li><li>Merge mind maps from all groups into a format that you can sort and categorize such as a spreadsheet.</li></ol><p>Here’s a mind map I drew with the Magnolia marketing team. The team uses the product every day to write and manage content. Their requirements are clearly centered around usability and author experience (AX). These topics have the most red stickers.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3cITTZlxKGj3Tge0cdCqMA.jpeg" /></figure><p>Each mind map is dominated by what the group does for living. You get a more accurate picture once you combine input from all groups.</p><p>For example, component-level personalization was only mentioned once in the Marketing team session. The item has no vote stickers. But this missing feature was raised again by other groups. Several respondents in the client survey also requested it. So overall component personalization is important and is now on the <a href="https://wiki.magnolia-cms.com/display/DEV/Roadmap#Roadmap-Componentpersonalization">Magnolia roadmap</a>.</p><h4>Short list</h4><p>Next, reduce the list to a reasonable size. We vetted the items against three criteria:</p><ul><li>Anything that was mentioned repeatedly got extra weight, one point per repeat. This allowed us to rank items by <strong>popularity</strong> and get rid of duplicates.</li><li>Next we weighed <strong>strategic importance</strong>. Some items just did not fit the product’s goals so we dropped them. For example, pre-built themes were requested a few times. A theme is a collection of resource files (CSS, JS) that gives a site its visual identity through the use of colors and typography. The issue with pre-built themes is that Magnolia caters to a difference audience than say Wordpress. Our clients are mainly mid-level enterprises for whom brand identity is very important. Can you imagine <a href="http://www.virginholidays.co.uk/">Virgin Holidays</a> deviating from their red-and-white look and picking a Magnolia-provided theme instead? While we could ship more pre-built themes it’s unlikely that enterprise clients would use them. They require unique designs.</li><li>Finally, we handed the short list to the developers for a <strong>feasibility</strong> assessment. Can we do these things? Are they technically feasible? Are there any items that would require so much work that they would blow the scope? A visual workflow designer was one of those items. Defining a workflow is too convoluted today. It requires too much expertise. It should be a user-friendly drag-and-drop exercise. Boxes and arrows. We want this feature in the product but it is such a significant amount of work that it needs to wait this round.</li></ul><h4>A roadmap is never final</h4><p>The <a href="https://wiki.magnolia-cms.com/display/DEV/Roadmap">current Magnolia roadmap</a> shows what we will work on next.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*G1jE6odWnntrErLwasJ-9Q.png" /></figure><p>We have buy-in from employees and partners. Now we need to convince the user community that these are the right items to work on. This blog post is a small part of that effort.</p><p>I don’t think a roadmap is ever final. It is a living, evolving document. Adapt. Communicate. Repeat.</p><p><em>Antti Hietala is a product manager at Magnolia. He is tasked with articulating Magnolia’s value proposition to sales and professional services. In constant contact with users, he feeds the product roadmap with front-line input. Antti’s key responsibilities include internal communication and the product roadmap. Follow him on Twitter </em><a href="http://twitter.com/antarctic74"><em>@antarctic74</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2d5c064bc801" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Pitfalls of public roadmaps]]></title>
            <link>https://medium.com/@AnttiHietala/pitfalls-of-public-roadmaps-3a589410d9fe?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/3a589410d9fe</guid>
            <category><![CDATA[roadmaps]]></category>
            <category><![CDATA[content-management]]></category>
            <category><![CDATA[product-management]]></category>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Wed, 16 Dec 2015 08:45:46 GMT</pubDate>
            <atom:updated>2015-12-16T08:47:16.028Z</atom:updated>
            <content:encoded><![CDATA[<p>In my previous post <a href="https://medium.com/@AnttiHietala/should-a-roadmap-be-public-808ade915df1#.ah4nt3q0m">Should a roadmap be public?</a> I argued that you are better off publishing your product roadmap. I compared vendor roadmaps in the content management industry to show that public is the norm.</p><p>In this post I look at two common pitfalls in public roadmaps and how to avoid them.</p><h4>Pitfall 1: Scheduling</h4><p>Usually problems arise not from publishing the roadmap as such but from attempts to schedule it. While it may be a good idea to set delivery deadlines internally, those dates don’t communicate well to the larger user community.</p><p>You may think that setting a public deadline demonstrates confidence in your ability to deliver on time. But it is unlikely that you can deliver everything by the chosen date. Even more likely, the plan will have changed by the time you reach the deadline.</p><p>It’s OK to share the roadmap as long everyone understands that a <strong>roadmap is a plan and not a commitment</strong>. Plans change when market needs change.</p><h3>Steve Johnson on Twitter</h3><p>@lukehohmann The key is for roadmaps to be a plan, not a commitment. A year from now, we&#39;ll likely change the plans substantially.</p><p>It’s a good idea to start this conversation inside the company. Explain the difference between a plan and a commitment to sales and everyone who communicates with the user community. Don’t sell the roadmap. Sell the current product.</p><h4>Pitfall 2: No theme</h4><p>The second pitfall with public roadmaps are unrelated items. A list of seemingly random features is a poor roadmap. It says two things:</p><ul><li>You are trying to please too many people.</li><li>The product lacks focus.</li></ul><p>Choose a theme. Pick features and improvements that fit the theme.</p><p>It’s easier to talk about an upcoming release when all features have a common theme. A theme is proof of focus and deliberate planning. Everyone who needs to communicate the roadmap will benefit from a coherent story.</p><p>The theme for <a href="https://wiki.magnolia-cms.com/display/DEV/Roadmap">Magnolia’s current roadmap</a> is <strong>author experience</strong>. Most items on the roadmap make authors’ lives easier:</p><ul><li>Tagging content</li><li>Referencing content</li><li>Back-end forms</li><li>Page editor improvements</li><li>Fix UX pain points</li><li>Component personalization</li><li>App navigation</li><li>Publishing of related content</li><li>Content type modeling</li><li>Article editor</li><li>Language-specific content structure</li><li>Search</li></ul><p>This thematic glue will help us explain the next major release to the user community.</p><p>It also makes a coherent story at the Magnolia conference where we offer more content for authors than ever before. <a href="https://conference.magnolia-cms.com/">Book your ticket!</a> ;)</p><p><em>Antti Hietala is a product manager at Magnolia. He is tasked with articulating Magnolia’s value proposition to sales and professional services. In constant contact with users, he feeds the product roadmap with front-line input. Antti’s key responsibilities include internal communication and the product roadmap. Follow him on Twitter </em><a href="http://twitter.com/antarctic74"><em>@antarctic74</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3a589410d9fe" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Should a roadmap be public?]]></title>
            <link>https://medium.com/@AnttiHietala/should-a-roadmap-be-public-808ade915df1?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/808ade915df1</guid>
            <category><![CDATA[content-management]]></category>
            <category><![CDATA[roadmaps]]></category>
            <category><![CDATA[product-management]]></category>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Mon, 14 Dec 2015 08:08:31 GMT</pubDate>
            <atom:updated>2015-12-16T08:46:46.484Z</atom:updated>
            <content:encoded><![CDATA[<p>Should you publish a product roadmap or keep it internal? In this post I argue that public is better. I compare vendor roadmaps in the content management industry to show that public is the norm. Once you decide go public there are couple of pitfalls to avoid.</p><h4>Public is better</h4><p>Public or private? Surprisingly, you may have little choice regarding this decision. Do your competitors have public roadmaps? If yes, you are pretty much expected to show yours. Other players in your field may already have set the expectation.</p><p>It is rather difficult to explain to a prospect why you don’t have a public roadmap if all your competitors have one. The prospect will think that you are weird. Not the cool kind of weird like Apple that uses secrecy to build up hype. The other kind.</p><p>By not publishing a roadmap you may <em>think</em> you are sending a message that your product is at the cutting edge and requires stealth. But prospects and clients interpret secrecy differently. They conclude that you either don’t have a roadmap or don’t know what to do next. The latter is worse because by sharing a roadmap you would get feedback and would have a better chance of working on the right things.</p><h3>Nandini Jammi on Twitter</h3><p>&quot;Unless you&#39;re Apple and you depend on mysterious product launches, sharing your roadmap will prob do you good.&quot; #prodpadtalks</p><h4>Roadmap round-up</h4><p>Let’s compare some vendor roadmaps in the content management industry. There’s a lot of open-source software in this field. Open communication often goes hand in hand with open source. Sharing a roadmap is more or less the norm. But not every company makes their roadmap equally easy to find.</p><ul><li><strong>Adobe Experience Manager</strong>: Adobe does not have a roadmap page you could simply look up. The Experience Manager product roadmap was presented at the EVOLVE15 community summit. The <a href="http://www.slideshare.net/lonistark/adobe-experience-manager-vision-and-roadmap/43">keynote presentation</a> slides are shared. See slide 43 for a short, high-level roadmap in five focus areas. To comprehend the items on Adobe’s roadmap you either need good knowledge of the product to understand why they were chosen or someone must talk you through the roadmap. This is a general issue with slides. Slides don’t really open up by just looking.</li><li><strong>Acquia &amp; Drupal</strong>: Acquia implements solutions based on Drupal. You need both roadmaps to understand what is happening in this community. Drupal Core is an open-source project so communication around the project is public. While there is no forward-looking roadmap you can follow the <a href="https://groups.drupal.org/core">project’s announcements</a> to get an idea of the team’s priorities. With Acquia the job gets more difficult. Acquia has decided not to publish a roadmap, which makes the company an outlier in this market. You must attend an exclusive <a href="https://www.acquia.com/resources/webinars/product-roadmap-preview-i-partner-exclusive-webinar">partner webinar</a> to get a glimpse into the product’s future.</li><li><strong>Hippo</strong> has a clear public <a href="http://www.onehippo.org/about/roadmap.html">roadmap page</a>. The items are minimal but you get a good idea where the company focuses on next. Hippo shows confidence in their ability to deliver the features on time by scheduling the roadmap. Scheduling is an exception among CMS vendor roadmaps. Most companies shy away from putting dates or even quarters in their roadmaps. Why? We’ll get to that in the next post.</li><li><strong>Kentico</strong>’s <a href="http://www.kentico.com/product/roadmap">public roadmap</a> is detailed and tells a story of each improvement area. This is a great way to tell prospects and clients where the product is heading. For Kentico 9, the company chose to focus on three areas: platform, Web content management and online marketing. A footnote rightly states that this roadmap is not a commitment. Another pitfall avoided.</li><li><strong>Liferay</strong>, like Adobe, doesn’t make it easy to find their product roadmap. Camouflaged in Liferay Detroit <a href="http://www.liferay.com/documents/4940947/0/2015+Roadshow+Roadmap+Presentation/659079bd-9c5c-4ec0-9a15-ade835f403ab?version=1.0">roadshow slides</a> (18 onwards) are high level themes such as performance and audience targeting. The slides alone don’t tell the whole story. You really need someone to talk through them and explain the improvements. An independent evaluator who considers the product will have little understanding of what the company actually plans to deliver unless they attend the roadshow.</li><li><strong>Magnolia</strong> provides a <a href="https://wiki.magnolia-cms.com/display/DEV/Roadmap">public roadmap</a> on their development wiki. The items are storified, with reasoning and detail provided. In contrast to Hippo, Magnolia does not put dates or release numbers on the deliverables. A roadmap is a plan and plans change.</li></ul><p>The CMS industry has a huge number of vendors, way more than is listed above. But even this small selection is indicative: publishing and communicating a roadmap is the norm.</p><p>Decided to go public? Great! See <a href="https://medium.com/@AnttiHietala/pitfalls-of-public-roadmaps-3a589410d9fe#.geqbu1s3e">Pitfalls of public roadmaps</a> how to avoid two common mistakes.</p><p><em>Antti Hietala is a product manager at Magnolia. He is tasked with articulating Magnolia’s value proposition to sales and professional services. In constant contact with users, he feeds the product roadmap with front-line input. Antti’s key responsibilities include internal communication and the product roadmap. Follow him on Twitter </em><a href="http://twitter.com/antarctic74"><em>@antarctic74</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=808ade915df1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Digital Transformation]]></title>
            <link>https://medium.com/@AnttiHietala/digital-transformation-5900fd8279cb?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/5900fd8279cb</guid>
            <category><![CDATA[disruption]]></category>
            <category><![CDATA[digital-transformation]]></category>
            <category><![CDATA[product-management]]></category>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Thu, 11 Jun 2015 14:25:07 GMT</pubDate>
            <atom:updated>2015-06-11T14:28:49.768Z</atom:updated>
            <content:encoded><![CDATA[<p><em>I am live-blogging the Magnolia Conference 2015 in Basel. In his keynote Boris Kraft argued that fear of disruptive technology killed Kodak. I argue that Nissan is in the same position today.</em></p><p>Did you know that Kodak <a href="http://en.wikipedia.org/wiki/Kodak_DCS">invented</a> the digital camera back in 1975?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Maio-Rc0ovmzoWRPLzNP-Q.jpeg" /></figure><p>In its heyday, Kodak was one of the most valuable brands in the world, synonymous with great photography. Despite its forward looking technology Kodak failed to secure a foothold in the digital camera market and ultimately filed bankruptcy in 2012.</p><p>What happened at Kodak?</p><p>Product managers <a href="http://www.forbes.com/sites/avidan/2012/01/23/kodak-failed-by-asking-the-wrong-marketing-question/">widely</a> <a href="http://mashable.com/2012/01/20/kodak-digital-missteps/">agree</a> that Kodak’s unwillingness to cannibalize its lucrative film camera business was the reason for failure. Kodak was making so much money in traditional film cameras that it hid the new digital product in the closet. It did not want to disrupt the market.</p><h3>Is Nissan the new Kodak?</h3><p>I argue that Nissan is in the same position today. The <a href="http://en.wikipedia.org/wiki/Nissan_Leaf">Nissan Leaf</a> electric car is a potentially disruptive product. It shares many characteristics with Kodak’s first mass-market digital camera, the DC40.</p><p>Kodak DC40 digital camera:</p><ul><li>Innovative, disruptive product</li><li>Poor photo quality compared to film: 0.01 megapixels</li><li>Poor user experience: no display to view photos</li><li>Poor storage: 4 MB, no external memory</li><li>Looks bulky and dorky</li><li>Kodak had a profitable business in traditional film cameras</li></ul><p>Nissan Leaf electric car:</p><ul><li>Innovative, disruptive product</li><li>Poor range compared to petrol cards: 117 km</li><li>Looks bulky and dorky</li><li>Expensive: USD 35,430</li><li>Nissan has a profitable business in petrol cars</li></ul><p>Knowing what happened to Kodak, what should Nissan do?</p><p>Nissan CEO Carlos Ghosn is on a quest to develop zero-emission vehicles. He authorized $5 billion to bring the Leaf to market — a gamble that prompted <a href="http://www.businessweek.com/autos/autobeat/archives/2010/05/nissans_ghosn_gambles_big_on_electric_cars.html">BusinessWeek to ask</a> whether he was crazy.</p><p>Ghosn knows the Kodak story. He understands that disruptive technology destroys old business models. Electric cars will replace the internal combustion engine as sure as the sun rises. Nissan’s today-profitable petrol car business will be gone one day. So Ghosn is acting now.</p><p>This is the nature of digital transformation. One company’s insight and investment in disruptive technology looks like fool’s gamble to bystanders. But letting the opportunity pass may turn out much more expensive.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5900fd8279cb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Custom Content Apps]]></title>
            <link>https://medium.com/technical-documentation/custom-content-apps-a1fad42422df?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/a1fad42422df</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 16 Dec 2014 11:15:53 GMT</pubDate>
            <atom:updated>2014-12-16T12:41:59.565Z</atom:updated>
            <content:encoded><![CDATA[<h4><strong>Create Magnolia content apps that access Web service data sources. Implement hierarchical containers and handle complex content items.</strong></h4><p>Consuming content from external sources is a standard practice in Web publishing today. Everybody has existing content: products, prices, inventory, images... This varied content is stored in many places: legacy applications, Web services and file systems.</p><p>Today, the key content management task is not writing editorial content. Ingesting small pieces of information from various sources and assembling them into a coherent Web offering has replaced writing. Any ecommerce site is testament to a very complex orchestration effort.</p><h3>Apps for custom content</h3><p>At Magnolia, we created a special app type to make consuming and managing external content repositories easier. <em>Content apps</em> are designed to manage structured data. They pull information from outside the content management system and present it to editors in a friendly app UI. Editors can enrich the content further and mix it into the website.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n1-uFfXNunzyGR9DIYDcnQ.png" /><figcaption>Example content app that manages antique cars</figcaption></figure><h3>Content app framework</h3><p>Because content apps are used often, Magnolia CMS provides a content app framework to make building them faster.</p><p>My developer colleague Christoph and I wrote extensive documentation for app builders, focusing on how to take advantage of convenience classes in the framework:</p><ul><li>A tutorial that walks you through building your first app. It’s a fun little exercise with antique cars.</li><li>An example that shows how to consume content from the file system, instead of the usual JCR repository.</li><li>Configuration reference for all pieces of the framework.</li><li>Design guidelines for making the app a joy to use.</li></ul><p>Armed with these docs we thought we had the bases covered. But we missed something rather crucial.</p><h3>Containers are complex</h3><p>As the first developers in the Magnolia community started building content apps they hit a wall we had not anticipated.</p><blockquote>“I am stuck on how to create a custom RESTful container. For me this is the starting point and it would be helpful to get an idea how this works. I don’t get the real idea from all these methods”</blockquote><blockquote>“For displaying custom content in a tree, there is no abstract container to extend, I have to implement a hierarchical container by myself.”</blockquote><p>Direct feedback from readers is my absolute favorite thing about working with open-source software. Everything I write is public by default. Anybody can comment, <a href="http://documentation.magnolia-cms.com/display/DOCS/My+first+content+app#comments-section">and they will</a>.</p><p>Developers had difficulty implementing the <em>container</em>. In a Magnolia app, the container represents the data source. It holds the content items, such as products, and provides methods for getting, adding and removing them.</p><p>We had failed to provide enough examples of containers. Granted, we had a standard container for accessing JCR data and <a href="http://documentation.magnolia-cms.com/display/DOCS/Content+app+with+non-JCR+content#Contentappwithnon-JCRcontent-Creatingacontainer">another for accessing the file system</a>. But what about data in the cloud? In a REST Web service? Hierarchical data?</p><h3>Hierarchical containers and items</h3><p>In a <a href="http://documentation.magnolia-cms.com/display/DOCS/Creating+a+custom+content+app">new tutorial</a> we focus on containers and complex content items. The example is an app that allows editors to browse photos from Flickr and use them on the site. Flickr has a Web service data source so it demonstrates well how to access a REST-based API.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*52uU7Ycg2kOTmZFFgTTq7Q.png" /><figcaption>Flickr photos in a content app</figcaption></figure><p>Flickr also presents us with the problem that developers faced when handling complex content items. Namely, not everything can be handled as a simple string. Flickr photos can belong to more than one album. This hierarchical relationship between photos and albums is best represented with a Java object item. The new tutorial dedicates a whole section to content apps with an <a href="http://documentation.magnolia-cms.com/display/DOCS/Content+app+with+an+Object+ItemId+and+different+containers">Object ItemId and different containers</a>.</p><p><strong>Start now</strong>: <a href="http://documentation.magnolia-cms.com/display/DOCS/Creating+a+custom+content+app">Creating a custom content app</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a1fad42422df" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-documentation/custom-content-apps-a1fad42422df">Custom Content Apps</a> was originally published in <a href="https://medium.com/technical-documentation">Technical Documentation</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Incredible Editable Screenshot]]></title>
            <link>https://medium.com/technical-documentation/the-incredible-editable-screenshot-ca50749b1c9f?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/ca50749b1c9f</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Wed, 22 Oct 2014 11:44:16 GMT</pubDate>
            <atom:updated>2014-11-04T15:19:12.329Z</atom:updated>
            <content:encoded><![CDATA[<h4>A picture is worth a thousand words. Sadly, those words are immune to search, locked away in a binary prison.</h4><p>Illustrations and screenshots are the most visually appealing part of technical documentation. In a stream of text, eyes naturally gravitate to images. They break the monotony of text and offer relief. Everybody likes a bit of color.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MB86TMZb4WGsB2oD3VV7FQ.png" /></figure><p>A carefully composed screenshot is packed with information. Best screenshots don’t show just an empty screen. They show sample data and expected input.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/623/1*8CGIMky_ZiB_wWj3JyfJ8Q.png" /><figcaption>Expected parameter format</figcaption></figure><p>Filled-in screens are always better than empty screens. A great screenshot can give the reader an idea, shortcut, or an opportunity for a quick solution — without even reading the text.</p><h3>Screenshots are tedious to maintain</h3><p>As useful as screenshots are, I find them tedious to maintain. My writer colleagues and I hated taking screenshots because we knew the maintenance pain that awaited.</p><p>Text is easy to revise but images are tedious. Here’s why:</p><ol><li><strong>Screenshots illustrate scenarios</strong>. The best screenshots show a complete set of inputs. Meaningful sample data demonstrates the purpose of a screen much better than random input or no input at all. When you update such screenshots you have to recreate the scenario. This means leaving documentation, feeding the sample data into the product, and coming back with a screenshot. The doc-product-doc roundtrip is time consuming.</li><li><strong>You can’t find invalid screenshots</strong>. The fundamental problem with binary content is that you don’t know if current screenshots are out-of-date because you can’t find them. No matter how diligent you are with file naming and metadata the binary content itself is not indexed. You might know exactly <em>what</em> the outdated data is but you can’t find <em>where</em> it exists. It’s maddening, really.</li><li><strong>New features come often. </strong>At Magnolia, we <a href="http://documentation.magnolia-cms.com/display/DOCS/Releases">release the product 15 times a year</a> on average. These releases introduce new features and improve existing functionality. They often invalidate current screenshots.</li></ol><h4>How about crowdsourcing the work?</h4><p>The inability to search for invalid screenshot bugged us. Computers could not find data locked in binary content so why not replace them with individuals? Use human intelligence to perform tasks that computers are unable to do.</p><p>We thought about organizing a <a href="https://confluence.atlassian.com/display/DOCSPRINT/Doc+Sprint+Home">doc sprint</a> to find and update invalid screenshots in documentation.</p><blockquote>A doc sprint is a short (two to three day) event when a group of people collaborate to develop a specific set of tutorials, often including the associated code.</blockquote><p>Doc sprints (“Screenshot Jam”, “Image Bash”, be creative!) are a great way to bond with your developer colleagues. You get some documentation and have fun working together.</p><p>However, you should be careful how you frame the task. Crowdsourcing works well for tasks that are motivating such as “We need better tutorials for our API”. A creative task can spur colleagues to write or review content. Hunting for invalid screenshots is not very motivating to be honest.</p><h4>Trust is our currency</h4><p>Does it really matter if screenshots are out of date? Isn’t the accompanying text more important?</p><p>Accuracy matters in technical documentation. If a screenshot does not match what the user sees on the screen then trust starts to erode.</p><p>Inaccurate documentation is the worst of the <a href="http://www.slideshare.net/jmusser/ten-reasons-developershateyourapi">10 Reasons Developers Hate Your API</a>. Trust is paramount. A sales pitch may exaggerate, marketing may boast, but technical documentation must be precise.</p><h3>Making screenshots editable</h3><p>We had an uneasy feeling that the issue was getting worse. With each release we got more material to maintain. More docs, more screenshots. So we decided on a radically different approach: <strong>replace images with text</strong>.</p><h4>Statistics: how many images</h4><p>We ran the numbers. Magnolia documentation had about 2,000 screenshots. The most common subject was the Configuration app. The app is basically just a table: rows and columns and text. Apart from the icons, there are no images.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*carhygYspGByv0cg9z0MKA.png" /></figure><p>We estimated that 40% of all screenshots showed the configuration tree.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/417/1*vooetRByhu1uSGtldthWiQ.png" /></figure><p>This finding was both embarrassing and promising. Embarrassing because we had taken so many screenshots of something that was basically just text. But promising because the prospect of turning 40% of images into editable text could eliminate half the time sink.</p><h4>Converting trees into tables</h4><p>We recreated the configuration tree as a table in Confluence wiki. Here’s what it looks like in edit mode:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1006/1*qonGZlQZRjRGT5w2t2yPEg.png" /><figcaption>Editing a table in Confluence</figcaption></figure><p>Couple of things to note:</p><ul><li><strong>Icon fonts. </strong>The tree node icons come from an icon font. <a href="http://css-tricks.com/examples/IconFont/">Icon fonts are awesome</a> because you can change their size and color instantly with CSS. We started using the same <a href="http://documentation.magnolia-cms.com/display/DOCS/Icons"><em>Magnolia Icons</em></a><em> </em>font that is used in the product UI. This level of reuse made us writers feel pretty cutting edge. The only aggravating detail is how we add the icons. A little helper macro is necessary because adding your own custom symbols to the Confluence <a href="https://confluence.atlassian.com/display/CONF42/Inserting+Symbols">symbols menu</a> is not straightforward.</li><li><strong>CSS class. </strong>We wrap the table in a Table Plus macro to assign a CSS class. This allows us to style the borders and colors so it looks like the product.</li><li><strong>Hierarchy. </strong>A tree is a hierarchical structure. In documentation we fake the hierarchy with indents. For presentation purposes it doesn’t matter but it makes the table much easier to edit. Ease of editing is a big deal because many non-writers contribute to Magnolia documentation. A casual user who wants to add such a table can copy-paste it from elsewhere and just indent their way to perfection.</li></ul><p>This is what the reader sees after we save the page:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_To0iIkmDcVFmPSyHoUpJw.png" /></figure><p>The result is incredibly similar to the product, nearly identical.</p><h3>Benefits</h3><p>Turning images into tables provided some unique benefits:</p><ul><li><strong>Everything is searchable. </strong>All the text that used to be trapped in images is now indexed. Googlebot crawls Magnolia documentation since it’s public and indexes the text inside the new tables. Users can <a href="https://www.google.com/webhp#safe=off&amp;q=contentViews+site%3Adocumentation.magnolia-cms.com">search for a property name and find examples of usage</a>. Editors can find where a certain configuration is used. We feel like a silo of closed content has been opened.</li><li><strong>Changes are quick. </strong>Writers no longer worry about having to reproduce elaborate scenarios to take a screenshot. Changes are quick to do. We edit “screenshots” just as we would edit text.</li><li><strong>Copy-paste works! </strong>Users can copy text from screenshots and paste it into their system. This is very useful for long values such as fully-qualified Java class names that must be typed correctly.</li></ul><h3>Future-proof mechanism</h3><p>What happens when the product changes? What if the tree looks different in the next version?</p><p>We already have tickets asking for usability improvements. The vertical alignment of nodes in the tree is not ideal. It is hard to see the parent node when the tree is tall. Readability suffers as complexity grows, and so on. The tree will change soon.</p><p>That’s OK. The table method is future proof. We can <strong>change the CSS to update all tables instantly</strong>. We don’t need to edit each table. Improved change management is a classic benefit of separating content from presentation. Style should not hard-coded into each piece of content but rather referenced from CSS. Experiencing this benefit in our own content was eye opening.</p><h3>Treachery of Images</h3><p>Finally, you might be wondering why we use a drop shadow around the configuration table. It’s not an image so why the makeup? Falsifying perfectly good text!</p><p>There’s a reason: <a href="http://en.wikipedia.org/wiki/The_Treachery_of_Images">The Treachery of Images</a>. We add a drop shadow to all images so that users don’t confuse documentation with the actual product.</p><p>You may think this is foolishness but it actually happens. Sarah Maddox wrote about a funny, but very true, <a href="http://ffeathers.wordpress.com/2008/03/08/ceci-nest-pas-un-screenshot/">case where readers clicked on buttons in a screenshot</a> and complained that they didn’t work.</p><p>As the product and its documentation look more alike, it is no longer clear which is which. Is that a clickable button or just a representation?</p><p>The direction in which API documentation is heading makes the line even more blurred. You can already embed functional examples into documentation. The docs effectively become actionable.</p><p>At Magnolia we use the <a href="https://documentation.magnolia-cms.com/display/DOCS/My+first+REST+request#MyfirstRESTrequest-SwaggerAPIexplorer">Swagger API Explorer</a> to help users learn our REST API. Swagger is embedded into the product. It shows what parameters and options the API accepts and <strong>it responds to your requests</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6eHgf1vpVMnGb6seswtB8A.png" /></figure><p>Swagger acts as live documentation that is always up-to-date. So we are already at the point where <strong>you can type input into documentation and get a response</strong>.</p><p>The little drop shadow that separates non-functional elements from the functional is not visual vanity. It’s error prevention.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ca50749b1c9f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-documentation/the-incredible-editable-screenshot-ca50749b1c9f">The Incredible Editable Screenshot</a> was originally published in <a href="https://medium.com/technical-documentation">Technical Documentation</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Recipe Cards in Technical Documentation]]></title>
            <link>https://medium.com/technical-documentation/recipe-cards-in-technical-documentation-96f0d146cec2?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/96f0d146cec2</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Fri, 10 Oct 2014 12:20:00 GMT</pubDate>
            <atom:updated>2014-12-02T15:10:30.029Z</atom:updated>
            <content:encoded><![CDATA[<h2>Recipe Cards in Technical Documentation</h2><h4><em>The </em><a href="http://www.istc.org.uk/our-publications/communicator/"><em>ISTC Communicator</em></a><em> magazine recently ran a photo competition with the theme “technical communication”. My winning entry featured recipe cards that inspired Magnolia app design guidelines. Here’s the story behind the photo.</em></h4><p>Collectable food recipe cards were all the rage in the ‘70s and ‘80s in Scandinavia. Each card had a photo of a dish in the front and ingredients and cooking instructions on the back. You would receive cards in the mail a few at a time. Many of my neighbors collected them. In the winning photo are my mom’s cards from Finland.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/896/1*afQ5G5tQlFno2lWSAbHyHA.jpeg" /><figcaption>Communicator magazine with the winning photo. Credit: ISTC</figcaption></figure><h3>Cards as documentation</h3><p>I think repice cards are a brilliant example of communicating <strong>condensed information</strong>. They are colorful, brief and to the point. The glossy surface can be wiped with a wet cloth so they are also <strong>designed for the point of use</strong>.</p><p>At Magnolia, we were inspired by the cards when we wrote <a href="http://documentation.magnolia-cms.com/display/DOCS/App+design+guidelines">app design guidelines</a>. We needed a format that was a <strong>joy to read</strong>. The core message of each app design guideline such as <a href="http://documentation.magnolia-cms.com/display/DOCS/Be+a+good+tablet+citizen">Be a good tablet citizen</a> had to be memorable even if the reader had little time.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hLhAU5td8b2IpAXU5mqBlg.jpeg" /></figure><p>The design guidelines are a success online. But we also printed them for the annual developer conference as accordion-like holiday postcards with perforated tear-off edges. The conference attendees loved them.</p><p>Since then I have noticed many responsive interfaces such as <a href="http://www.google.com/landing/now/#cards">Google Now</a> using the card model. <a href="https://speakerdeck.com/christse/patterns-of-card-ui-design">Card based user interfaces</a> are hot right now.</p><p><em>Credit: </em><a href="http://www.istc.org.uk/our-publications/communicator/"><em>ISTC Communicator</em></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=96f0d146cec2" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-documentation/recipe-cards-in-technical-documentation-96f0d146cec2">Recipe Cards in Technical Documentation</a> was originally published in <a href="https://medium.com/technical-documentation">Technical Documentation</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why I Don’t Do EPUB]]></title>
            <link>https://medium.com/technical-documentation/why-i-dont-do-epub-1573472c9236?source=rss-5d934ed5da4e------2</link>
            <guid isPermaLink="false">https://medium.com/p/1573472c9236</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 15 Jul 2014 09:53:53 GMT</pubDate>
            <atom:updated>2014-07-15T11:50:16.084Z</atom:updated>
            <content:encoded><![CDATA[<h4>Lots of work for little benefit</h4><p>I write technical documentation for open-source software. The content is available <a href="http://documentation.magnolia-cms.com/display/DOCS/">publicly on the Web</a>. When <a href="http://forums.magnolia-cms.com/forum/thread.html?threadId=ff1acc42-c5bc-4c34-99da-c94b1246b5fe&amp;page=1">asked</a> to provide the same content as ebook for offline reading I weighed the pros and cons of EPUB production and finally decided against the idea. Here’s why.</p><h3>The case for ebooks</h3><p>Offering content in ebook format makes sense when:</p><ul><li>You are a print book publisher. Today, it is mandatory to offer electronic versions of print titles to stay in business. <a href="http://www.bbc.com/news/technology-19148146">Amazon sells more Kindle ebooks than print books</a>. The consumer expectation is clear.</li><li>You charge money for your content and want to find a new distribution channel. This is the situation magazine and newspaper publishers find themselves in. Ebooks may help keep current subscribers pinned or attract new eyeballs.</li><li>Your content is <a href="http://en.wikipedia.org/wiki/Long-form_journalism">long form</a>. Reading multi-page content on a desktop or mobile device is not ideal. Readers may prefer a device that is designed to make longer reading comfortable.</li><li>There is no extra effort involved in producing ebooks, so why not?</li></ul><p>The first three cases don’t really apply to my content. The documentation I write is already on the Web, for free, and the pages are short.</p><p>But the fourth case might be true. I was curious. If producing an EPUB does not cost any extra time or effort, why not give it a go?</p><h3>Collaborating in a wiki</h3><p>First I need to explain why I write technical documentation in a Confluence wiki. There may be other tools that are better at producing EPUB that I may be shutting out.</p><p>Wiki is my tool of choice because I don’t write alone. Many users contribute to Magnolia documentation. Since most contributors are not technical writers I need to make contribution very easy for them. Wiki is a fantastic collaboration tool to beginners.</p><p>Any unnecessary obstacles such as forced structure (DITA) or formatting conventions (Markdown) stand in the way of getting content written. A casual user who wants to contribute should be able to just start typing. I will take care of the formalities. Wiki is great for that. Collaboration and ease of use are killer features that make an open documentation project work.</p><h3>Success criteria</h3><p>I estimated that for EPUB production to be worth the effort, the following criteria would have to be met:</p><ul><li><strong>Self service</strong>. Users should be able to export content from Confluence to EPUB on their own. I don’t want any part in it. I prefer to spend my time figuring out what content users need and writing it. Fighting with output formats? No thanks.</li><li><strong>Measurable</strong>. I like to know what pages users read, even offline. Are certain pages read offline more than others? What search terms are popular? Google Analytics already tells me that for online docs. Is there a way to get similar analytics about EPUB usage?</li><li><strong>Feedback</strong>. Users ask questions and comment on the documentation. This two-way relationship results in better content. A clear <a href="http://documentation.magnolia-cms.com/display/DOCS/Feedback">feedback channel</a> is essential for continuous improvement. Is there a way to get feedback through EPUB?</li></ul><h3>Scroll EPUB Exporter plugin</h3><p>Since I write content in a Confluence wiki I downloaded the <a href="https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-epub">Scroll EPUB Exporter</a> plugin. The plugin is provided by K15t Software and available on the Atlassian Marketplace.</p><p>The plugin is easy to use and the output looks professional, even without custom theming.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*k7CORiUVCxTErh-rYTllHg.png" /></figure><p>My first impression was positive — this could actually work. The plugin even adds a new menu item in Confluence that allows end users to export EPUB on their own. That was a key feature in meeting the self-service criteria.</p><p>However, the plugin has two unsolved issues that erode its usefulness for me.</p><h4>1. Exporting pages per label</h4><p>One of the most popular topics in Magnolia documentation is the <a href="http://documentation.magnolia-cms.com/display/DOCS/Technical+Guide">Technical Guide</a>. It’s not a single page but a collection of pages that help newcomers understand and evaluate the product. The technical guide is also the most relevant piece for offline readers.</p><p>While each topic in the guide is fairly short, together they make long-form reading. Users should be able to export all the pages in the guide to EPUB in one go.</p><p>The Exporter plugin can export multiple pages per label but it assumes the labeled pages reside under the same parent page. In my case they don’t. The technical guide topics are spread all over the Magnolia documentation wiki space.</p><h4>2. Ordering pages</h4><p>There is no way to influence the order in which pages are exported.</p><p>The technical guide topics should be read in a particular order. This is somewhat rare. Typically readers pick and choose the topics they want to read. As a writer, I have little influence over the reading order and mostly that is fine. However, anyone new to the product really should read the technical guide topics in the order I put them. Basics first.</p><p>The EPUB Exporter plugin unfortunately exports pages in the same order as they are in the page hierarchy. The first page in the hierarchy becomes the first page in the EPUB. This is not how the technical guide topics are ordered in my wiki space.</p><p>To their credit, the K15t Software support team was responsive and helpful. While they could not solve either issue on the spot they suggested I vote up the tickets:</p><ul><li><a href="https://k15t.jira.com/browse/VSN-1026">VSN-1026</a> Page Maps (aka Topic Maps)</li><li><a href="https://k15t.jira.com/browse/EXP-347">EXP-347</a> Let Users Define Export Structure.</li></ul><p>Due to these issues my “self-service” criteria was only met partially. While users could export single pages to EPUB on their own, any ordered collection of topics such as the technical guide was going to have a weird order.</p><h3>Analytics</h3><p>I use Google Analytics for online documentation. But offline I don’t know who reads what. Can EPUB report analytics?</p><p>Ebook analytics packages such as <a href="http://www.epubdirect.com/ebook-sales-analytics">ePubDirect</a> focus on reporting distribution, basically how many times an EPUB is downloaded. While interesting, downloads does not help me write better documentation. I need to know usage-specific statistics such as what are the most-read pages and what search terms are readers using.</p><p>I looked for a way to embed analytics into the EPUB itself. A company called Hiptype was after the same thing in 2012:</p><blockquote>Hiptype analytics idea was built around inserting a snippet of code into ebooks. When you read the ebook that snippet of code would track what you were doing and send data back to Hiptype’s servers, where it would be collated and served up to the relevant publisher.</blockquote><p>Unfortunately, Hiptype shut operations down due to lack of interest from ebook publishers:</p><blockquote>The snippet of code initially only worked in iBooks because that platform supported Epub3, while getting similar data out of a Kindle or Nook ebook required the cooperation of Amazon or B&amp;N. Neither liked the idea.</blockquote><p>So that killed my criteria #2: Measurable.</p><h3>Feedback</h3><p>The final success criteria was the ability to get reader comments from the EPUB. Such functionality does not exist in the EPUB format natively. It’s just a content format. The devices don’t seem to have a standard way to collect and send feedback either. I kind of expected that the device could capture the page title and let the user send an email to an address I provide in the EPUB.</p><p>The K15t support team recommended that I add a link in the EPUB that takes the user back to Confluence for commenting. Sending readers back to online docs would be an extra hoop but the recommendation was reasonable.</p><p>Criteria #3 Feedback was kind of solvable.</p><h3>Summary</h3><p>With two out of three criteria unmet, I pulled the plug on the plugin.</p><p>Producing EPUB would mean extra work for little benefit. For readers who still prefer offline, Confluence allows you to download individual pages as PDF. This is out of the box functionality. The PDF format is widely supported by e-readers and requires not extra effort from me.</p><p>I hope my experience helps you make a decision if you are weighing the options. If your documentation is already in a Web-native format and publicly available, producing an offline format may not be worth the effort.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1573472c9236" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-documentation/why-i-dont-do-epub-1573472c9236">Why I Don’t Do EPUB</a> was originally published in <a href="https://medium.com/technical-documentation">Technical Documentation</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>