Category: Authoring

The Dreamweaver project

At the start of this blogging assignment, I decided I would do a review of Dreamweaver and what shall forever be known as “the Dreamweaver project”. Two months later and twelve days before the Dreamweaver project deadline, the best review I can come up with is that Dreamweaver and HTML/CSS coding are an apt metaphor for the difference between understanding and doing.

The background

The background is simple. We created a storyboard for a small website. Now we have to develop this website in Dreamweaver. I have never designed a website nor used Dreamweaver before. I have enough knowledge of HTML and XML to understand most of the code when I read it. I thought that knowledge, access to w3schools.com, and more online research would be sufficient. How naive!

The process

I am now on my third attempt. First, I tried to create the website from scratch. The most accurate description for this attempt is a big, sarcastic “LOL”. Anyway, my template was almost correct, but I was stalling, I did not see how to untangle the situation, and I had to expect as much trouble with every feature I created.

I proceeded simultaneously with my second attempt (building the site as a table) and third attempt (using the only vaguely similar Dreamweaver template available) to see which one would be more efficient to handle. The Dreamweaver template won. My template index.html is not perfect, but I can improve it later on. For now, it’s functional and I have to move on.

Still, I have to downgrade my ambitions for this project from my storyboard. I asked my brother for his opinion on my storyboard because he is experienced in coding and web design. He is that person who will answer your questions with an obnoxious “Oh! That’s so obvious! Just do [something that is definitely not obvious].” So, hearing him say “You couldn’t start easy, could you?” was a relief.

I have had this feeling that expectations for this project are too high. Designing the storyboard with skewed expectations of my abilities, the learning curve, and the usability of Dreamweaver set me up for a world of failure and frustration.

Understanding vs doing

Like with any language, understanding the HTML/CSS code of a website and “writing” a website are two massively different things. My usual strategies for learning to write in a language would broadly include:

  1. Mastering the rules (grammar, syntax, keywords, etc.)
  2. Reading as much as possible to increase my vocabulary and internalise a natural writing style
  3. Writing content using what I have mastered and increasing complexity progressively

Based on my experience so far, coding is different from most languages I learnt before. There may be several, slightly different ways to code the same feature, but I find beginners have less freedom for creativity than with other languages.

For example, when in my third year of Russian, I had to write complex text analyses with a limited vocabulary, a pocket dictionary, and no Internet. As a beginner, I had to find ways to express myself with these limited resources. I had to rephrase my thoughts in simpler terms or terms that I could access. This is one of the hardest exercises I have ever done, but also one of the most useful for communication and learning in general.

I have tried to reproduce this process with this project without success despite access to incredible resources. I improve by small increments but reviewing how I solved each issue, I find that I solved my biggest issues through pure luck instead of identifying the root causes. I am trying to improve my skills by monitoring and analysing my progress, but I cannot consider luck as progress. A crucial piece is missing and I think it is a deeper understanding of HTML, CSS and web design rules, like how each coded feature interacts with the rest of the code. I would need a lot more time and overseen practice through e-learning courses for this.

Conclusion

No doubt the Dreamweaver has provided an opportunity for deeper learning, forcing me to evaluate and adapt my strategies. Unfortunately, the main strategy I can think of is to spend more time learning about the code and Dreamweaver through e-learning courses, but time is not an option anymore.

How much time would I need? My summer development project is coming up and I am supposed to build a much more complex website with Dreamweaver and WordPress. I have to keep in mind the overall development project and my priorities – the first is content design of a learning resource for the web, the second is WordPress hosting. The tool used is a secondary consideration. There’s the lesson of the Dreamweaver project.

We’re halfway there

Virtual Team Project – Week 4

Here we are, in the last week of editing. Well, maybe not. I am sure that the translation team’s work will highlight ways to improve the source text. But I will focus on editing this week. Based on discussions with other students in the programme and the blog posts of some of these students, this task has proved challenging for many teams.

The Team 2 process

Two weeks ago, our first draft served as a process for the writing /editing team to research the product and structure in sequential order all the content we needed to tackle. Each of the four writing team members participated in this draft one after the other, building on the previous writer’s input. This was the research & structure part of our process. This first draft had ca. 1,400 words (200 words over the maximum limit).

Then, one writing team member pared down this content to its most essential components and steps and proposed style guidelines. We were now at ca. 650 words (250 words under the minimum). This gave us a clear view of our goal: we needed to make all these steps as usable as possible, in plain language, and we could add between 250 and 550 words. 250-550 words are really not that much when they include the cover, table of contents, captions and glossary.

For the last ten days, the writing team has been adding content to this draft and editing it based on each other’s feedback. Members involved in the translation and final proofreading also offered feedback. As tracked changes piled up, every few days, we resolved feedback and created an updated version. By Tuesday of this week, we could see that the editing flow had dried up.

As a translator, I always found editing – in particular, self-editing – to be more draining than the actual writing or translating. Firstly, the brain tends to read faster than the eyes, guessing what is written instead of reading it, so you can easily miss typos and obvious errors, especially when you know the text already. So, editing requires a higher level of attention to detail. On the other hand, editing is a never-ending process because you can always improve the text. Any new pair of eyes can bring new improvements. The risk, then, is to lose sight of the big picture. Editing is about striking a balance between insufficient and excessive criticism, but also knowing when to take a step back.

A new pair of eyes

On Wednesday evening, we still had unresolved feedback and we still had to do most of the formatting – which would require more feedback. We needed to do all this by Friday in order to be on time for the second test before the final proofreading. Among all team members, I realised that I was the most likely choice to offer a new point of view.

In general, I think the project manager should avoid taking on development tasks. The project manager leads and coordinates the team, and he /she makes decisions. If he /she produces work as part of the development, his /her objectivity might be called into question. During the two weeks of writing and editing, I skimmed over the content, made suggestions to get the feedback rounds started and then I concentrated on other members’ feedback. I avoided creating content. However, by Wednesday, it became clear that I might be able to unlock our situation by making editing decisions, so I resolved the feedback, did the formatting (except the cover), and inserted the graphics we had.

My intention was not to impose arbitrary decisions – I kept a copy of all the feedback for reference. But when you are stuck, implementing ideas can be the solution to decide whether to discard or keep them. Only by seeing what your ideas look like in context can you really test their adequacy.

Also, I am glad that the writing team only implemented limited formatting until Wednesday. They focussed on sequencing the content appropriately, which provided a clear template for me to propose a visual identity with MS Word styles, a glossary, navigation links, etc. Though the formatted document looks very close to the previous version, the different fonts, colours, spacing, etc., seemed to help the writing team to see the content with fresh eyes. It also moved us toward the testing phase as team members reported potential compatibility and usability issues.

Had we followed a different writing process, we could have avoided this situation or solved it differently. For example, we could have split the writing /editing team between two writers and two editors, with the editors working simultaneously or sequentially. In case of editing fatigue, the writers could have taken over again. The two writers and two editors would have worked in cycles. Instead, because of clashing schedules, the writing /editing team organically adopted a four-people collaborative configuration. This configuration worked for this small, non-technical project, but I recognise that it may be too messy for larger scope projects. Laziness is also a risk, especially in a one-person editing team: feeling relieved that you have overcome your editing inertia, you may be tempted to think that your editing work is finished.

Conclusion

When I write or translate, I tend to spend most of my time on the first draft. I want it to be as close to the final version as possible. Not that I hate editing. I don’t, and editing will happen anyway. But projects like this virtual collaboration highlight the biggest challenges of editing: getting stuck in never-ending feedback and striking a good balance between excessive corrections and missed errors. While the solution I described here is not viable for every project type and configuration, I believe that, with careful follow-up, it can be a valid option to overcome inertia after several editing loops.

All hands on deck

Virtual Team Project – Week 3

In week 3, all members of Team 2 continued to be mobilised and focussed delivering a “First Draft” to the translation team by Monday 25 February and we learnt two major lessons about drafting instructions and the need to be flexible. As always, all the time mentions refer to the Irish/French time zones unless otherwise indicated.

A mobilised team

We are very lucky to have a team that is completely mobilised to reach our goals. Here are a few examples.

The 1st draft (not the “First Draft” above) was ready on Sunday 10 February afternoon and we were aiming for a 2nd draft by Sunday 17 February. On Monday 11, one writing team member said that she would start working on the 2nd draft to propose some writing guidelines. By Tuesday 12 evening, she had edited the whole draft and aggregated a PDF with the guidelines she used! Similarly, our graphics designer prepared the first round of graphics within two days based on the 1st draft. We were now a few days ahead of schedule with fully-functional guidelines and graphics to review. My hat’s off to them!

Starting each new discussion on WhatsApp, I can’t help but feel like I am barging into each team member’s life and asking him/her to drop everything at once. I hope that this is only an impression and I have told my teammates that I do not expect answers urgently. I only intend to start a discussion. Nevertheless, I haven’t had to wait long to get a question answered or a discussion started. This week, whenever someone made edits or provided feedback, the other team members – including the translation team – reviewed these edits and this feedback shortly after. When we discussed running the first test on the 2nd draft this week instead of waiting next week (more on that later), the tester made himself available immediately.

With our busy schedules, we did not maintain this pace all week, but everyone made sure to maintain good communication. For example, one team member informed me that his schedule this week made it hard for him to follow the WhatsApp group chat, but that he wanted to participate in the team’s efforts. We agreed that I would send him a private message whenever we needed his input. I understand his position because it mirrors my fears about using group chats to make decisions. I appreciate the fact that he was forthcoming about the situation.

To make discussions easier to follow, I thought of proposing set chat hours as suggested in “Take The Pulse Of Your Virtual Team”. However, based on my teammates’ schedules and the time differences, that would leave very short windows to discuss the project each week. Decision-making may be more efficient as a result, but it might be too efficient. We haven’t found a time window for live team meetings yet, and I am worried we would become Team Robot. Still, in an effort to facilitate communication and updates, I asked that all team members state all their feedback in the latest draft and graphics files. This is not as easy as it sounds with a WhatsApp group chat, but I expect this will be particularly helpful with the next round of edits.

Lessons in flexibility

When we decided on tasks and a schedule, we did not take enough time to do an in-depth analysis of the structure of our instructions. Of course, we discussed what we would cover in the instructions. We would talk about creating a WordPress account, creating a blog, writing/deleting a blog post, assigning categories, collaborating on a blog, etc. I think we all knew the importance of defining the structure of one’s content before writing, but we fell victim to the curse of knowledge. “Sure, the WordPress user interface is not very usable, but the process is straightforward.” It is, once you know it.

With everyone’s feedback, we realised that we had not covered all possibilities, like the availability of a Google sign-in option, the display of alternative languages depending on your location and device settings, the need to provide directions even if screenshots are available, the need for definitions for a “non-technical audience” (what are keywords for?). When we realised that I did not get the same starting page as the others because I am based in Ireland with a French device, we decided to run the first test on the draft this week instead of next week.

As mentioned earlier, the tester moved right away and we all benefitted from it. His feedback as a non-user of WordPress unlocked more feedback from the rest of the team. This was the Russian doll of feedbacks, with each new finding unleashing a new set of feedback and content to include. Fortunately, the 2nd draft had gone down to less than 700 words, so adding content won’t be a problem.

Conclusion

This past week showed once again that our team is responsive, that it takes initiative and that it is committed to reaching the team’s goals despite busy schedules. Maybe we should have prepared a detailed structure for our content as a first step, but I think that starting with a rough draft worked in our favour. Firstly, we were ahead a schedule thanks to this draft and it lifted our spirits and encouraged us to keep the pace. Secondly, the 2nd draft put the team in usability testing mode. It allowed everyone to participate in defining style guidelines and in structuring the content.

We are handing in the text for translation in one week. Until then, let’s see what new challenges await us.

References

Sookman, C. (2018) ‘Take The Pulse Of Your Virtual Team’, IAAP Edge, 21 July, available: https://edge.iaap-hq.org/2018/07/21/take-the-pulse-of-your-virtual-team/ [last access 17 February 2019].

Strings Authoring for Localisation

Talking about intercultural communication in class this week, we delved into several topics, including localisation and writing with an international audience in mind.

According to Bert Esselink (2003), localisation “revolves around combining language and technology to produce a product that can cross cultural and language barriers”. Though at first localisation applied mostly to software applications, today global web communication means that a great number of technical authors write for localisation. Localisation best practices are a broad topic, but this post focusses on some practical strings authoring advice from a translator’s point of view.

Internationalisation

The #1 best practice in localisation is to internationalise your product. This means you should ensure that your product and your content will enable localisation for your present and future markets. “Future” is key because all languages do not have the same requirements, and you should strive to “future-proof” your code and content from the start.

Internationalisation has technical and linguistic aspects. Technical aspects include ensuring your platform and code will support the specificities of each locale, including different character sets and orientations. Three pieces of advice here:

  • Prefer Unicode to maximise compatibility.
  • Do not hardcode text in graphics. Otherwise, you will need to extract the text for translation, and create new localised graphics. Different characters and right-to-left orientation will add extra work.
  • In doubt, check with a localisation specialist before authoring.

You can find more technical advice online, for example on web pages by Microsoft, Google Developers, Mozilla, and Oracle. As you can see on these pages, technical best practices are not enough to get your strings ready for localisation.

Authoring strings for localisation

As a translator, technical issues tend to be solved when I receive the strings, but linguistic issues may remain. Why should you care? After all, it is up to the translator to solve these issues. Yes, but:

  • The translator most likely translates the strings out of context in a computer-assisted translation (CAT) tool. He/she only sees the translatable text and the description keys/strings. More on that shortly.
  • If the translator misinterprets a string and introduces errors in the translation memory (TM), these errors will persist until a) you do the in-context review (best-case scenario) or b) a diligent user (the world?) gives you feedback.
  • If a translator sends you questions for each unclear strings, this translates into extra work and time lost for both of you – maybe extra cost as well.

Below I provide a few pieces of strings authoring advice based on the biggest pain points I have experienced as a translator.

#1 Rule: String descriptions are the best

Unfortunately, translators often localise user interfaces without any visual support. They may have access to the live website/app, but the international version may not be available yet. A demo version of the software may not be in the cards. Translators may have access to screenshots, but these do not display the whole content. There is a simple solution that is beneficial to all the users of the strings files – descriptions. In most strings files, you can insert a description key to clarify the translatable content that follows (button, menu item, alert, etc). This is very useful especially for very short strings. Consider these examples:

  • “Bookmark” and “Contact”: Buttons? Menu items?
  • “Empty”: Button? Message alerting you to an empty folder?
  • “Login”: Form field? Button? Yes, it should be “Login” (form field) and “Log in” (button). Without context, spelling mistakes can create confusion.

You can also insert a description string to clarify some items: what do the placeholders replace? If there are numerical variables, what is their numerical range? Etc. A description string is very helpful in case of length limits (see below). If you struggled to stay within a limit, the translators are likely to struggle as well. In case of a very short string, explain what the button, message or menu item does. It will help to find a shorter alternative.

Keep it short, but do not sacrifice clarity

Clarity is essential in technical communication, but even more so in web/software localisation because length constraints are frequent. Many languages need more space than English to express the same idea. For example, even if instructed to “keep it short”, languages like Latin languages, German, etc., can be up to 30-35% longer than English. Make every word count. This is especially true for menu items, app strings, and Google Ads. If there are absolute length limits:

  • Do not reach the limit in English. Plan for the 30-35% expansion rate. Of course, that may not be possible if the limit is 6 characters.
  • Avoid abbreviating. Abbreviating may not solve length issues in some languages. If available, choose an alternative that does not require abbreviating. If not available, provide a description string.
  • State the limits clearly as a number of characters. CAT tools can highlight strings that are over these limits.

Because of length limits, you may resort to complex noun clauses. Please don’t. If you can. What is a complex noun clause? In a complex noun clause, several words form a complex term without any clear functional link between each word. Typically, one word is the subject and the other words modify this subject. Consider these two examples from the Oracle Guidelines:

  • “Empty File” – Is the file empty? Is it a button to empty the file?
  • “Quantity Changes Impact Rate Master”. Do changes in quantity impact the rate master? Does the quantity change the impact rate master?

As the source of most translators’ questions, complex noun clauses are the best argument in favour of description strings. If you cannot avoid such clauses, clarify them.

List the strings in a logical, not alphabetical, order

Here is why you should avoid ordering strings by alphabetical order, and prefer a logical order by webpage, menu, section, type of string, etc.:

  • A logical order makes it easier to refer to a specific string in case of questions or updates.
  • Picture this: there are two “Empty” strings in the strings file. One is a button in Menu X, and the other is a message in Menu Y. You want to edit the message to clarify it, but both strings follow each other in alphabetical order and there is no clear description key. How long will it take you to identify the right string? And the translator?
  • Concatenated strings are unlikely to be displayed together in alphabetical order. Eg.: you split a sentence into String #1 and String #2. If you order the strings logically, String #2 will be directly after String #1, providing the translators with the right context. Alphabetical order makes this unlikely. Have dozens of concatenated strings and this becomes a puzzle.

On the topic of concatenated strings…

Avoid concatenating, and be careful with placeholders

When concatenating strings, you assume that grammar and syntax rules are the same in all languages. Mozilla provides a good example of concatenation issues and recommends using placeholders instead. This is invaluable advice, but it is not always enough because abusing placeholders and variables also causes grammatical issues. Consider this real-life example:

“Delivery is scheduled {0} {1} {2} from {3} at {4}”

There were no explanation regarding what {0}, {1} {2}, {3} and {4} meant. The author could not say for sure what each stood for. Searching the other strings, we solved the puzzle:

  • {0} stands for “every”
  • {1} is a numerical variable ≥ 1
  • {2} stands for “day(s)”, “week(s)” or “month(s)”
  • {3} is the start date
  • {4} is the delivery location

This works (somehow) in English, but it does not work in French, with or without concatenation. “Day” and “month” are masculine while “week” is feminine, and “every” has to agree in gender. Also, the numerical variable is not needed when it equals 1. For {3}, the proposition is “à partir de lundi 11 février”, but it is “à partir du 11 février”. Here is the French translation with text instead:

Every 1 day(s): “La livraison est programmée tous/toutes les 1 jour(s) à partir de {Date} à l’adresse {Address}”

To be grammatically correct, it should read:

“La livraison est programmée tous les jours à partir de {Date} à l’adresse {Address}”

To reduce the number of alternative strings, we end up with awkward English and localised strings. At least two variants of “{0} {1} {2}” are necessary in French, one for masculine and one for feminine (we could live with the unaesthetic “(s)”). Languages like Russian require even more variants because there are three possible declinations for “day(s)”, three more for “week(s)”, and another three for “month(s)”, depending on the preceding number.

Do not overdo it with placeholders. Limit the number of placeholders that contain variables. If you cannot, define with target linguists the number of variant strings you need to provide for localisation.

Conclusion

String authoring should abide by technical communication guidelines regarding clarity and cultural sensitivity. More than other content types, strings must be concise, but never at the expense of clarity. Though it may seem like a burden at first, providing descriptions and inserting variant strings to account for different writing rules will make strings management easier for you and your localisation teams.

References

Esselink, B. (2003) “The evolution of localisation”, Multilingual Computing and Technology, available: http://www.intercultural.urv.cat/media/upload/domain_317/arxius/Technology/Esselink_Evolution.pdf
[last access 10 February 2019].

Globalization Documentation (n.d.) Microsoft, available: https://docs.microsoft.com/en-us/globalization/
[last access 10 February 2019].

Internationalization (i18n) open source libraries and APIs (n.d.) Google Developers, available: https://developers.google.com/international/
[last access 10 February 2019].

Localization content best practices (n.d.) MDN Web docs, available: https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_content_best_practices#Avoid_concatenations_use_placeholders_instead
[last access 10 February 2019].

Understanding Translation Issues (n.d.) Oracle, available: https://docs.oracle.com/cd/E17984_01/doc.898/e14698/translation_issues.htm
[last access 10 February 2019].