Finnotype

There's a bug in Confluence 4.2 that generates identical IDs for same-name heading elements ( CONF-17962 ). The issue is fixed in Confluence 4.3 but here is a workaround for those stuck with Confluence 4.2 or earlier. Multiple same-name headings on the same page are OK. In fact, they are quite common. When I document objects that have similar properties I need to repeat headings. The problem in Confluence 4.2 is that you can't link to such headings (anchors). The link always points to the first occurrence of the heading. Example : I use the following heading structure in message types documentation: Banners Behavior Levels Examples Looks like How to show Alerts Behavior Levels Examples Looks like How to show Notifications Behavior Levels Examples Looks like How to show Confluence generates IDs using a pattern where page title and heading are concatenated with a hyphen in between: <page title>-<heading name> As a result, the IDs ...

I spotted this CSS class being used in Chrome keyboard shortcut help. I applied the style to our  keyboard shortcut documentation  at Magnolia. Now the shortcuts look like actual keys. That was a quick way to add a bit of polish. .kbd { background-color: #f7f7f7; border: 1px solid #ccc; color: #333; font-size: 13px; line-height: 1.4; text-shadow: 0 1px 0 #fff; font-family: Arial,Helvetica,sans-serif; display: inline-block; padding: 0.1em 0.6em; margin: 0 0.1em; white-space: nowrap; -webkit-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset; -moz-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset; box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset; -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; } Here's the result:

Magnolia Conference 2013 has left town. Time to sum up the results. I organized a Doc Jam session to collect feedback on documentation. If you haven't been to a jam session before, it's pretty simple: Name a documentation topic that is missing. Help us write a table of contents for it. Here are the top three topics proposed by the attendees. 1. Managing system health How can an administrator tell a system is healthy? Symptoms and numbers to watch out for (too many nodes?) Collecting system statistics. Events to log routinely vs. events to log when in trouble. Serious vs. harmless log entries Issue scenarios like what to do when the search stops returning results. Idea! Create a Health app that provides vital stats. 2. Replicating your environment Replicating a complete site to a dev or test environment.  Configuration to change after cloning. Changing subscribers to avoid publishing content to production. 3. Activation (publishing) best practic...

It is not easy to write text that translates well. We just started translating  Magnolia CMS documentation  into Chinese. Here are five insights we learned on the way that make work easier for authors and translators. 1. Chinese Wikipedia is your friend Many software terms are well known in their original English form and may not need translation. For proprietary and established terms, check if Chinese Wikipedia translated them. If Wikipedia translates the term, you probably should too: http://zh.wikipedia.org/wiki/Web容器 http://en.wikipedia.org/wiki/Web_container If Wikipedia does not translate the term, you likely don't need to either. http://zh.wikipedia.org/wiki/Java_Servlet http://en.wikipedia.org/wiki/Java_Servlet Using commonly accepted, established terms avoids a lot of confusion. Users who read general documentation about the Java platform and Web technologies can apply the terms they learned. 2. Lower case and upper case don't exis...

In Magnolia 5 technical documentation we have a page titled  Location, location, location . The page explains how the system identifies where you are with a URL history fragment. Examples: I am in the Pages app , editing a page named  about : #app:pages:detail;/demo-project/about:edit I am in the Contacts app , viewing a contact named ldavinci : #app:contacts:browser;/ldavinci:treeview: Very nifty! This means you can bookmark any location and go back there instantly. The document about location fragments is very technical. But the title is a pun. The phrase "location, location, location" is used in real estate for the three most important factors in determining the desirability of a property. The phrase was coined by Harold Samuel, a British real estate tycoon. This in an example of a safe joke technical text. Native English speakers get the punchline and have a giggle. But even non-native readers get the point. For them, the repetition emphasizes impo...

We are launching  Magnolia Academy  today. It is a new independent learning resource that teaches Magnolia 5 step-by-step. Code samples, exercises, tests and videos help you learn in a way that suits you best. Magnolia Academy targets learners across the globe: a developer in Beijing who wants to put a star on their CV or a system admin in São Paulo who does not have access to classroom training. The idea of online courses was raised as we realized that we cannot offer personal training everywhere in the world. Magnolia's growth projections for the next two years made the situation imminent. As problems go, this one is a very nice problem to have. It's good to have growing demand. Responding to that demand just needs quick acting. The Documentation, Services and Development teams at Magnolia collaborated to produce online learning modules that range from basic system setup and project best practices to templating and app development. Check it out and post your fee...

It is a telltale sign of failed user experience when you need to write "click" in technical documentation. When did you last read the Twitter user guide? Me neither. Using Twitter is pretty self-evident. Just look at the app and tweet. You don't need documentation. Self-explanatory tasks need no docs. They should be intuitive enough to complete by looking at the user interface and relying on past knowledge. Creating a folder? Moving a file? Cropping an image? Everyday stuff that should be obvious. A huge amount of effort goes into perfecting the user experience in consumer apps. Intuitive UX can lift an app above its competition just as disastrous UX can sink it. Great UX is infectious. It sets user expectations. Users start demanding that software at the workplace be just as simple. In that way, consumer software forces enterprise software to adapt. For  Magnolia 5 , we broke our necks to make Web content management simple. Instead of features ga...

Eleven years ago Tim Berners-Lee said that the next logical step for the World Wide Web was  semantic . The idea was that one day machines could read and understand Web pages. Content would be tagged in a meaningful way: a date would be tagged as a date and an address as an address. Relevance would replace ambiguity. Finding, sharing and combining information would become easier. Today the semantic Web remains a pipe dream. Here is quick proof: When in Basel, Switzerland, go to Google News . Look at the top stories. See a bunch of stories about bank liquidity requirements? Minimum capital levels for financial institutions? How are these stories relevant to you being in Basel? They are not. Google is doing simple string matching. It detects your geographical location to Basel. It then finds news stories that say "Basel". It doesn't know that the Basel III agreement that regulates bank capital adequacy just happens to be named after the city ...

Have you seen the recent boom in infographics? Everybody and their mom is doing them. Infographics are used to illustrate  complex data , timelines , trends ,  cheat sheets  and much more . They make complex processes easier to understand and visualize trends that you can't see with the naked eye. Can infographics be used in technical documentation? At Magnolia we drew a  roadmap  for migrating from Magnolia CMS 4.4 to 4.5. It is a winding road that involves many tasks. Each milestone is explained on a wiki page in detail. Here are the design guidelines I used in case you want to create an infographic of your own. Use a diagram tool  such as Visio or OmniGraffle. You will be using lots of boxes and connectors and resizing and scaling the elements. Working with vector shapes is easier and results in a sharp image. Max width 1000 px . Keep the width under 1000 pixels. This is a size that everyone can see without scrolling horizontally. ...

– Austrasse, that's in my neighborhood! – Wettstein, I know where that is! – The river is almost complete. We set up a thousand-piece  Basel city map puzzle at one of the desks at Magnolia. (Yes, we sometimes work too.) The puzzle is made by Helvetiq, the company that makes the trivia quiz game of the same name. It turns out that a puzzle is a great way to learn about your co-workers. This is useful if you have lots of new staff like at Magnolia . People walk by the desk and solve a piece here, another there, explaining where they live and how they know the city. I can't imagine a better ice breaker.

Update! Picnik is closing on April 19, 2012 .  This is sad news. I really liked working with the product. Please sign the  Don't Close Picnik petition ! A subset of Picnik features is available in the Google+ Creative Kit but, crucially, the Photo Bucket is not. This means that the custom circles and arrows we use to annotate images are gone. At Magnolia, we recently started using Picnik  to annotate screenshots. We wanted a casual but obvious way to draw the reader's attention to an image detail. In this post I explain why we chose Picnik and how it is working so far. Picnik is a photo editor that runs in the browser. You may have seen it as the embedded photo editor in Picasa Web Albums. The requirements that drove us to a Web-based tool were: No OS lock-in . We have technical writers working on Windows 7, Vista and Mac OSX. It is difficult to find a screenshot tool that works on all those platforms. Skitch  is awesome on the Mac but a Wi...

In this post I show how to improve textarea usability with a Twitter-style character counter. Validating form input length is a common strategy for reducing errors. So common in fact that the  HTML specification  provides a maxlength attribute for input fields. Starting with  HTML5 , multiline  textarea fields support the attribute too! <textarea id="message" rows=4 maxlength="100" /> Since it is always better to prevent an error than catch one the user already made, here are two ways to improve textarea usability in Magnolia CMS , making sure the user knows how many characters are allowed. Display the character limit The obvious improvement is to display the character limit. In Magnolia CMS, you set the limit on the form field. The system saves it to a maxLength property in the repository. Render the length on the page: Copy the formEdit.ftl  script which renders input controls. Create folder  Templa...

In this post I show you how to create coupons using the Magnolia Imaging module . I start with a background image and overlay the special promotion text. Campaign specific details are managed in the Data module while static text is configured in the Imaging module. Let's start by registering an image generator . For this purpose I use the ImageOperationChain generator since it allows me to execute multiple image operations one after the other. My image operation chain will be called coupon and it outputs PNG files. The first image operation in the chain, loadImage , loads a background graphic. I am using the ClassPathImageLoader class which can retrieve an image from the classpath. (You can also load from DMS , website or external URL .) By default, a Magnolia webapp's classpath includes any JARs in /WEB-INF/lib and any classes and resources in /WEB-INF/classes . I copied my background graphic into the latter and named it coupon.png . Here's the operation configur...

AdminCentral is a Magnolia CMS user interface where administrators and editors work. In this post I show how to configure menu permissions for a custom user role. AdminCentral provides menus for common tasks. When you click a menu, workable items are displayed on the right. You can hide menus and move them around to promote often-used items or deny permission to items that users should not be able to access. Magnolia CMS ships with typical roles such as superuser, editor and publisher. While a superuser can see everything, editors only see items that are relevant to their job. Permissions for custom roles Suppose your organization has a very specialized editor role, Category Editor, who is responsible for maintaining a taxonomy of categories. Categories are tags that help site visitors find related, interesting content. Categories are managed in a custom data type under the Data menu. The  demo-project website  has an example taxonomy consistin...

This post was inspired by Amit Patel's question  on how to add images in a Magnolia category cloud. Thanks Amit! What is a tag cloud? Tags are words or short phrases that describe content such as articles or photos. A tag cloud is a weighted lists of those tags displayed as a group where popular tags are given more visual weight than less popular tags. The visual weight is accomplished by making popular tags larger or bolder. Here's a tag cloud from  Flickr  with tags that people use on their photos. Another cloud with trending Twitter topics. Magnolia category cloud Magnolia's category cloud paragraph has the same principle. Articles on a website are tagged with categories to make it easier to find related content. Categories can be displayed in a cloud just like tags. The Magnolia category cloud is an editorial paragraph rather than compiled automatically from popularity statistics. This means that editors can set the weights to promote c...

This post belongs to a series about  search engine optimization  (SEO) with Magnolia CMS. Today we look at increasing your site's link popularity. Search engines place strong emphasis on your site’s link popularity. Links from external sites, especially highly ranked ones, increase your site's rank. The more links targeting your site from external sources the better. There are countless ways to build links and a comprehensive discussion on this is beyond the scope of this paper. Some ways that Magnolia can help to build incoming links are: By developing a blog on an external domain to promote your main site. The Templating Kit allows you to manage multiple sites in a single instance . A forthcoming social media module will facilitate effortless integration with social media networks that have become a must for success on the Web. Social bookmarking provided in many Magnolia templates. Friendly URLs make creating external links intuitive and easy to create.

This post belongs to a series about  search engine optimization  (SEO) with Magnolia CMS. Today we look at inserting keywords in page titles and meta elements. Page titles are an extremely important SEO factor. Search engines give titles considerable algorithmic weight and use them as headings on search results. Titles should include keywords and, where appropriate, your company name for branding purposes: <title>Magnolia - Finance, Insurance & Banking</title> Description meta elements on the other hand do not add much to page relevance, but should not be neglected: <meta name="description" content="Magnolia's largest group of Enterprise Edition customers is from the..."> Their content often appears below the title in search results: The relevance of keywords stipulated in the keyword tag once had great impact, but this is no longer true. Actual page content is now far more relevant. Still, a keyword tag should be included: ...

This post belongs to a series about  search engine optimization  (SEO) with Magnolia CMS. Today we look at optimizing images. Great images enhance your site visually and enhance SEO rankings, provided they are properly optimized. Google and other search engines offer image-specific searches. A high rank in these searches increases your visibility. Search engines cannot read the content of images, and therefore must rely on accompanying text and tags. Best practices include: Image alt attributes with a short description of the image, for example.  Keyword-rich image file names. yellow-roses.jpg is far more descriptive and relevant than img003.jpg . Size and quality optimized for quick loading. Crisp, sharp images look better in thumbnails displayed in search results, and are more likely to be linked to by other webmasters. Captions that aptly describe the image assist vision-impaired users. Width and height specified in the element. Many browsers render a page ...

This post belongs to a series about  search engine optimization  (SEO) with Magnolia CMS. Today we look at redirecting traffic. Redirecting is the practice of sending requests to alternative destinations. Typical reasons to redirect are: Pages have moved due to site re-organization but search engines and users still have the old URLs in their indexes and bookmarks. Without redirection traffic going to the moved pages is lost to 404 errors. Identical URLs serving the same content lead to duplicate content issues as crawlers mistake each URL for a separate site. This is known as the "canonical URL issue" in SEO parlance. It is not uncommon to have example.com , www.example.com , and example.com/index.html deliver the same content. Sometimes there is a valid need to display the same content on multiple pages. These factors adversely affect SEO but they can be corrected by redirecting the incoming request to an alternative URL. There are several ways to redirect, but the ...

This post belongs to a series about  search engine optimization  (SEO) with Magnolia CMS. Today we look at categorizing content. Usability and SEO go hand-in-hand. Categorizing content allows visitors to find related and similar content with ease. Logical, keyword-rich categories provide intuitive navigation of a large collection of content. Categorization offers a range of opportunities to improve internal linking, visibility, and keyword density. Common uses of categories are tag clouds, and links to overview and landing pages. Although content tagging is an effective technique, tag clouds in particular have been abused. Bloggers saw them as a keyword-stuffing opportunity, and search engines have developed techniques to combat this trend. Magnolia allows you to create custom categorization taxonomies. You can tag articles with categories to support browsing of related content. This feature can be extended and adapted to suit your needs. By default, you can categ...