Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > 2016 > June

Writing for Alfresco

Posted by ahealey Jun 14, 2016

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 -

writing for alfresco

I’ve recently been moved out of the Aikau team in order to provide some assistance to a feature team that are using Aikau. This change in role has given me a very useful insight into the problems that developers have when using Aikau. When working on Aikau I only ever get to see a fragment of the overall implementation - I get very little context so I never know if the overall implementation is being done in a sensible way.

It’s important to remember that we never think of Aikau as being “done”. Our widgets are always open to further iteration to either add more capabilities, refactor them for better performance, improve the design and fix any bugs. We also don’t consider them to be an exhaustive set by any means - we know that more widgets will be needed.

What we don’t know is what bugs exist, what features could be added and what widgets are missing. We rely on our feature teams, customers, partners and community to tell us what is required.

When I started working on the feature I was given in the new team I almost immediately identified one bug and 3 features (1,2,3) that were required. This wasn’t a brand new requirement for my new feature team but these requirements hadn’t been identified.

Trying to act like a good community citizen I raised these as issues on JIRA and then being a model community citizen I created pull requests to fix the problem and add the features following the well defined acceptance criteria.

Of course it's much easier to do this when you have an awareness of what is available and how things are meant to work in a framework when you have been involved in the development of that framework. Having said that I really want to encourage you to just ask the question and start the dialog with us.

It should hopefully be clear from the closed issues that we’re more than happy to answer questions when they’re asked.

The flip side of the coin is to not start a dialog but to simply complain about something without trying to dig into the details like with this blog post published last week. Whilst I understand that something might not be immediately obvious when trying to use Aikau (we’re well aware that documentation could be improved, we just haven’t been allocated the resources to do enough about it) we will try and help you if we can - even if that help is simply explaining why something is the way it is.

We aren’t promising to implement all your feature requests (far from it in fact!) but we are committed to genuine bugs in our coding (meaning a defect in the intended behaviour of an individual widget or service).

We’re starting to see increased Community interaction - more issues raised, more traffic, more GitHub stars. What we’d really like to see is more pull requests - and if something is blocking you from making a pull request then we’d like to know what that impediment is so that we can remove it.

This is going to be especially important during my reassignment as it means that we might not be able to implement community requested features as we have in the past - but we will endeavour to try to stay on top of the bugs that you raise.

Thanks again for your ongoing support !

Filter Blog

By date: By tag: