Writing for Alfresco

Showing results for 
Search instead for 
Did you mean: 

Writing for Alfresco

Active Member II
0 0 2,024

A year ago we published a survey, asking you if Alfresco products use User Interface (UI) terms and language that makes sense.

We had a great response from 200 Alfresco users, developers through to end users, and since then we’ve been busy putting the feedback you gave us to good use.

Survey Results

We’ll have a look at what we’ve been up to in a minute, but first (as promised previously) we’ll show you some of the survey results. We found that the feedback to the following statements was particularly useful in validating our thoughts behind conducting the survey in the first place.



It was clear from these results that we could make improvements to give real benefit to the day-to-day experience of Alfresco users.

When we looked at the detailed responses, many of you felt that the language and tone we used was perfectly ok. But there were plenty of useful comments, both general and specific, on what could be improved.

And one thing came up again and again; that the language in Alfresco products is

“too technical!”

This is something we were already aware of, and if you check this previous post then you’ll see that we’d been addressing it in recent new features and products. So it was great to see that we've been heading in the right direction.

What we did after the survey

Once we’d sifted through and evaluated the feedback, we chunked it into a backlog of areas to fix. There are a lot of words in Alfresco - the Alfresco platform and Alfresco Share alone contain well over 40,000 individual words, and that’s before we get on to Activiti, Records Management, Alfresco Mobile, etc.

Using the survey feedback we identified the key places where we could make improvements, and we now have a playbook in place to make these fixes.

Of course, at the same time as we were doing this our engineers continued to be busy developing new products and features, all the time adding new terminology.

Writing for Alfresco

As we built on how we wanted Alfresco terminology to be, we decided to set up some guidelines to ensure that we could develop consistency across the product range. We used a number of tools to decide what the Alfresco “voice” should be, including the survey results, a ton of analysis of other research data, user testing, and of course, looking at other products.

As we looked at the tone and voice guidelines for a well-known email app, Thomas De Meo, our VP of Product Management suggested that the app was “the kind of guy you want to hang out with”. That struck a chord and so we thought, well what do we want Alfresco to be? The answer was “the kind of person you want to work with”.

We built on that and have now published a set of guidelines – “Alfresco Voice - writing for the user interface”. This covers all aspects of product language including what tone to use and what words to avoid, how to write for a global audience, keeping it simple, and how to make that error message useful instead of an overly-technical nightmare.

The style and tone in this guide is how future Alfresco products and features will sound. And we’re gradually working through the existing terminology to bring it in line.

User Assistance and Experience Design representatives now work with the Alfresco Engineering agile teams to design the terminology in parallel with feature development. This means that the words you read in our products have been carefully designed and considered to compliment the UI and user level, and to make Alfresco products simple to use.

We hope that you’ll notice the difference, and see how we’ve taken all your feedback on board. And if you’re an Alfresco developer, then go ahead and use the guidelines for your own add-ons or customizations - docs.alfresco.com/writing-for-alfresco.

writing for alfresco