<?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[Technical Documentation - Medium]]></title>
        <description><![CDATA[Best of developer docs - Medium]]></description>
        <link>https://medium.com/technical-documentation?source=rss----b2c4dd3d1fbf---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Technical Documentation - Medium</title>
            <link>https://medium.com/technical-documentation?source=rss----b2c4dd3d1fbf---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 02:12:30 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/technical-documentation" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Custom Content Apps]]></title>
            <link>https://medium.com/technical-documentation/custom-content-apps-a1fad42422df?source=rss----b2c4dd3d1fbf---4</link>
            <guid isPermaLink="false">https://medium.com/p/a1fad42422df</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 16 Dec 2014 11:15:54 GMT</pubDate>
            <atom:updated>2014-12-16T12:41:59.565Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qT9dOWoK__V1Ks8X0ysiLQ.jpeg" /></figure><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----b2c4dd3d1fbf---4</link>
            <guid isPermaLink="false">https://medium.com/p/ca50749b1c9f</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Wed, 22 Oct 2014 11:44:47 GMT</pubDate>
            <atom:updated>2014-11-04T15:19:12.329Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LKP-beonsln7_IxwBRK0Zg.jpeg" /></figure><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----b2c4dd3d1fbf---4</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[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hLhAU5td8b2IpAXU5mqBlg.jpeg" /></figure><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[How to Design and Build Great Apps with Magnolia 5.3]]></title>
            <link>https://medium.com/technical-documentation/how-to-design-and-build-great-apps-with-magnolia-5-3-e7fa1c50f5c1?source=rss----b2c4dd3d1fbf---4</link>
            <guid isPermaLink="false">https://medium.com/p/e7fa1c50f5c1</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 15 Jul 2014 09:54:38 GMT</pubDate>
            <atom:updated>2014-06-25T12:02:31.162Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tsEixq466k1EeqMppl1ewg.jpeg" /></figure><p><em>I am live blogging at the Magnolia Conference 2014 in Basel, Switzerland. I attended a presentation by Andreas Weder and Mikael Geljic on </em><a href="http://www.magnolia-cms.com/conference/program/presentations/apps.html"><em>How to Design and Build Great Apps with Magnolia 5.3</em></a><em>.</em></p><h3>What is a great app?</h3><p>According to Andreas and Mikael, a great app is one that brings <strong>value</strong> to users. An app doesn’t have to be complex. In fact, the simplest apps are often what users love best. An app that does one thing really well helps the user save time or effort.</p><p>In the context of Magnolia CMS, a good app also <strong>plays well with other apps</strong> and the system. Your app should fit the Magnolia tools around it, providing unique functionality that makes the whole work well together.</p><p>Andreas compared apps to ingredients in a great dish. Individually, each small ingredient may seem meagre and insufficient. Don’t fall for that illusion! Resist complicating things. When you cook the little ingredients together, the result is a satisfactory user experience.</p><h3>App design guidelines</h3><p>Continuing with the cooking metaphor, Andreas showcased <a href="http://documentation.magnolia-cms.com/display/DOCS/App+design+guidelines">Magnolia’s app design guideline cards</a>. They are like the recipe cards your mom collected in the 70&#39;s. Remember? They came with magazines. Each card was a small recipe you could easily follow.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*03fm8laVQiMl7hueaS3p1w.jpeg" /></figure><p>Put the cards to good use. Your app will play well and is also be easier to build because the recipes encourage taking advantage of ready-made functionality provided by the Magnolia app framework.</p><h3>Example: Photo Scout app</h3><p>Mikael showed an example app that lets you find photos on Instagram. When you find a great photo, you can suggest that the photo be added to your the local collection of assets in Magnolia.</p><p>It was quite a neat little app. Mikael made good use of things that are readily available in the app framework such as sending a task to the Pulse.</p><h3>Start with a storyboard</h3><p>When designing apps, Andreas recommends to start with a storyboard. Just a simple story that covers the essential pieces.</p><p>You can download a storyboard stencil and print one yourself. Don’t worry if you can’t draw well. Everybody can sketch!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wOgt02hj9t0kOAw_stLTuQ.jpeg" /></figure><h3>Ask a series of questions</h3><p>Ask yourself these questions:</p><ol><li><strong>What type of app should I build?</strong><br>Magnolia provides two basic types: content app and custom app. In the example that Mikael showed, the choice was easy. The content app framework already had a suitable thumbnail view and an image provider for displaying photos. The actions for sending tasks are also part of Magnolia Community Edition.</li><li><strong>How should I configure settings?</strong><br>Here Mikael suggested the Small app layout. It is good for single things that you don’t touch often, such as entering an Instagram tag for searching photos. Create a mockup in a tool such as Balsamiq mockups if you think it helps. But pencil and paper work too.</li><li><strong>How do I communicate with people in the loop?</strong><br>Use tasks or messages. Send them to the Pulse messaging hub.</li><li><strong>How do users interact with the app?</strong><br>Take advantage of views such as the thumbnail view which is a good fit for browsing images. Use a light dialog for quick tasks like sending a task or message. Not heavy.</li></ol><h3>Conclusion</h3><p>I was involved in writing the app design guidelines so I know the subject quite well. I thought the presentation made good use of them. It was also interesting to hear the audience ask about the new <a href="http://documentation.magnolia-cms.com/display/DOCS/Content+connector">content connector</a>, a Magnolia 5.3 feature that decouples app from the JCR storage.</p><h3>About the presenters</h3><p><a href="http://www.magnolia-cms.com/conference/program/speakers/andreas-weder.html">Andreas Weder</a> is Magnolia’s Head of User Experience. He’s mainly responsible for Magnolia 5&#39;s new user interface and is its key author. Designer at heart, Andreas has more than 20 years of experience in software development and user interface design.</p><p><a href="http://www.magnolia-cms.com/conference/program/speakers/mikael-geljic.html">Mikaël Geljic</a> is a UI developer specialized in rich web applications and usability. At Magnolia he mainly takes care of UI components, user interaction and theming.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e7fa1c50f5c1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-documentation/how-to-design-and-build-great-apps-with-magnolia-5-3-e7fa1c50f5c1">How to Design and Build Great Apps with Magnolia 5.3</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[Content Is Broken]]></title>
            <link>https://medium.com/technical-documentation/content-is-broken-ca07c973c8f1?source=rss----b2c4dd3d1fbf---4</link>
            <guid isPermaLink="false">https://medium.com/p/ca07c973c8f1</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 15 Jul 2014 09:54:19 GMT</pubDate>
            <atom:updated>2014-06-27T09:10:21.428Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Xz8hR2OFjACahqgDJgLbfg.jpeg" /></figure><h4>And How to Fix It</h4><p><em>I am live blogging at the Magnolia Conference 2014 in Basel, Switzerland. I attended a presentation by Brian Bentzen on </em><a href="http://www.magnolia-cms.com/conference/program/presentations/content-strategy.html"><em>The Good, The Bad &amp; The Ugly Content Strategist</em></a><em>.</em></p><p>As somebody who writes content for living I am always on the lookout for good tips. Brian Bentzen delivered quite a blow in his presentation: I am probably doing it wrong. But there’s hope!</p><h3>The Good, the Bad and the Ugly</h3><p>There are three kinds of content strategists:</p><p><strong>Ugly</strong> content strategists have writing skills but they don’t do anything serious about content. They just write. “Looks fine, publish.” If you can identify yourself as an ugly content strategist (as most people do), you might have thought about content strategy. You may even have a plan but you don’t follow it. The plan is in the drawer. You are too busy producing content. “I don’t have time to think about strategy!” The problem is, if you keep doing this, at some point you will be removed from your position. It is just a question of time. Ugly strategists are thrown out.</p><p><strong>Bad</strong> content strategists realize that their content is not working. Realizing that you have a problem is a major step forward. You try to create good content but fail. Creating content that works in the organization or in the market is difficult. Your intentions are good but your execution sucks. You keep saying “Content first, content is king!” but you also fail to produce what is relevant.</p><p><strong>Good</strong> content strategists turn the idea upside down. They don’t start with content, they end with it. After you have done your homework, writing matching content is the last thing you do.</p><p>That was bad news. I admit falling into the “I don’t have time to think of strategy” trap. It’s a sticky trap. I end up losing even more time writing wrong stuff.</p><h3>How to write content that works</h3><p>Here’s the fix:</p><ol><li>Find out what is your company’s business. You cannot define the business yourself. You must ask. Go talk to the CEO.</li><li>Define digital goals. Once you know the business goal, figure out how you can support it with digital content.</li><li>Support user tasks. Solve the user task. You need to understand what the user wants to accomplish.</li><li>Measure output. This is tricky. Measuring content (words, hits, likes whatever) is pointless. Such numbers don’t tell if the content works. What matters is whether the user can do his task with your content. For example, if the user task is to buy a train ticket, measure whether they can do it. Can they do it under 4 minutes? Can they do it under 1 minute?</li><li>Write content. This is the last step. After you have figured out all the steps above, now is the time to write. Whatever you write will be relevant, targeted, and measurable.</li></ol><p>These were great tips. Hard message but sobering. Fortunately there’s a method to follow.</p><p>Follow Brian Bentzen at <a href="https://twitter.com/brianbentzen">@brianbentzen</a></p><p>Sad news: <a href="http://en.wikipedia.org/wiki/Eli_Wallach">Eli Wallach</a>, the actor who played Tuco (Ugly) in <em>The Good, the Bad, and the Ugly</em>, died yesterday aged 98.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ca07c973c8f1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/technical-documentation/content-is-broken-ca07c973c8f1">Content Is Broken</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----b2c4dd3d1fbf---4</link>
            <guid isPermaLink="false">https://medium.com/p/1573472c9236</guid>
            <dc:creator><![CDATA[Antti Hietala]]></dc:creator>
            <pubDate>Tue, 15 Jul 2014 09:53:54 GMT</pubDate>
            <atom:updated>2014-07-15T11:50:16.084Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1vHA-QYfYLoxLEuvWndUlA.jpeg" /></figure><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>