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...