Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > Author: ahealey

User Assistance at Alfresco

Posted by ahealey Feb 9, 2017

If you’re reading this blog then chances are you know about, where the official Alfresco help and documentation is available. Everything you read (or watch) there is created by Alfresco’s User Assistance (UA) Team, who are based out of the Engineering headquarters in the UK.


Do I keep reading? Is this going to be interesting?

You'd better believe it!
We’ve got news of career opportunities at Alfresco, plus details of how we’re looking for more community involvement.


What is UA at Alfresco?

The UA team are the conduit between an engineer’s brain, and the people who use Alfresco software. We take something complicated, and explain it in terms that can be easily understood.


We work on everything that Alfresco produces, with every single user type in mind. Whether you’re an end-user of Alfresco Mobile looking for help on the go, or a seasoned Alfresco developer using Aikau and looking for the latest Share extensions, the UA team are here to help.


Things we do


Who we are

The Alfresco UA Team is managed by Helen Mullally, who with 8 years under her belt is an Alfresco old-hand. Whilst we aim to be as T-shaped and cross-skilled as possible, naturally we each have our own strengths. So one person will lead or specialise on videos, another on API docs. It’s not exclusive though, I might work on videos one day and API docs the next.


How we work

Each product development team at Alfresco has a member of the UA team embedded into it. (Each team is made up of engineering and QA, a product manager (PM), a scrum master (SM), a member of the UX team, and us). The UA representative attends team standups, sprint reviews and retros. This means that we’re able to write in parallel with development and release documentation in parallel with products.


With UX and the PMs we define both the UI copy and any in-product help that’s required. This way of working means that not only is the writing in Alfresco products clear and consistent, but also that we can take advantage of findings from user research to address actual user scenarios in the online help.  

We do use Alfresco ourselves, to store, manage, and publish all of our content, with a publishing tool built on top of Alfresco called Componize.


Do you interact with the Alfresco community?

The honest answer is probably not as much as we should. Last year we took part in a Tech Talk Live with Richard Esplin, and have spoken in the past at Alfresco Summit. This year we intend to become more active within the community, and will be attending Beecon in April.


We do regularly check and occasionally contribute to the Alfresco forums, and we receive regular feedback from the feedback form in the online help, some of it good, some of it brutally honest. All feedback is great and helps us to improve.


Can the community contribute to the docs?

We haven’t opened up the documents for comments as this can be a nightmare to sort the good from the bad from the spam. It’s something we’re always considering though, so maybe in future. For now, you can use the feedback form mentioned above to suggest improvements to the documentation. We read every single piece of feedback and have had some good exchanges with people who’ve contacted us this way. You can also raise an ALF Jira ticket using the "Documentation" component.


Andddd… (drumroll)… coming soon we’re going to be running a program for user-created videos.


We’ll be inviting you to create your own Alfresco help videos using our templates – the best of these we’ll make available on and our YouTube channel. Watch out for the announcement here and on Twitter later this year.


We’re hiring!

The team is currently growing to keep up with the expanding product development teams. If you’re technically-minded, want to help out other Alfresco users, and can put your ideas into words then get in touch. You don’t need to have a tech writing or user assistance background. We’re also looking for super-technical Alfresco developers who have a flair for writing. Maybe you have a background in social media, content marketing or article writing.


Take a look the two job descriptions, and if you think you're a match then get in touch.

Technical Writer

Technical Writer (API/Developer Documentation)


These roles will be mainly based out of our Maidenhead headquarters and you’ll need to be authorized to work in the UK.



If you want to find out more then you can contact the UA Team at

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

Interested in providing feedback and insight to simplify Alfresco’s products?


Over the last few releases of Alfresco One and Alfresco Community Edition, you may have noticed that the user interfaces (UI) have been updated with a slicker, more modern feel. The Alfresco User Experience and Engineering Teams have put a lot of time and thought into creating products that look great and are simple to use. And we’re not finished yet…

What you may not have noticed is that we’ve also been gradually updating the function terminology (everything from button labels to error messages) in the product, to make the language feel more natural, and less clunky or technical. When you use Alfresco’s products we want the terminology to feel like a natural conversation rather than a barrier; terminology that will help guide you, rather than language you have to Google to find out what it means to move forward.

A great example is the new Search Manager feature in Alfresco One 5.0. This feature started life as Faceted Search Configuration – we hope you’ll agree that the name we settled on is a bit friendlier and more commonly used!

Now we want to get you, our end users, involved… We’ve published a survey asking for feedback on what works, what doesn’t, and what direction you’d like to see us go in with the terminology in Alfresco’s products.

We need direct feedback from all members of the Alfresco family – community and enterprise users, developers, architects, partners, consultants, anyone that uses Alfresco’s products! Please let us know what you think – the survey should take no more than 5 minutes to complete and will run until the end of July. Thank you in advance as your feedback will have a direct impact on helping Alfresco product’s speak your language.

Following the survey, we’ll collect and analyze the results to discuss the feedback we’ve received. Once a plan is in place, we’ll report back our findings through a follow-up blog post, so stay tuned.

Click here to give your opinion.

Filter Blog

By date: By tag: