Have been playing different roles for 8 years working in tech. From software engineer, analyst, consultant to manager and back at developer role recently. Here is a story of the recent project that I involve in and my thoughts on that. As a , you did great work. You solve problems, coming out with new solution to tackle the business needs. developer But you don’t like documentation. Because you think, as a good developer like you, people should just read the code! Code will tell you everything. That’s the most reliable documentation. Well, it’s the most reliable and source of truth, but doesn’t mean reading code is the most human friendly and most effective. I work on an interesting project recently — right to left (RTL) our application, to support languages like Arabic, Hebrew. This project also including refactoring the current way of handling translation. Here is the screenshot on how a page look like before and after RTL. sample screenshot Sound simple? Yes and No. We have teams working in different countries and totally different timezone. For example, my 11pm would be 4am on the other side. Since these changes will impact all UIs, all teams across countries must be aware of it. Some of the Learnings Great Solution only Awesome when You Share it As a newbie in the company, I realise the teams here don’t share their architecture and implementation normally. Some of my awesome colleagues have lay some foundation on the new translation implementation, but the knowledge doesn’t really share to anyone including when the project was handed over me. You don’t Know What You don’t Know Other teams, be it teams in the same country or other countries, is not entirely aware on the translation and RTL changes. Since they are not aware, therefore, when some teams are adding new UIs, they do not cater for RTL design and using the old way to implement translation. the new way of translation implementation, causes some missing translation on the UI in some specific condition because the translation moved from sync to async call. The tests conducted didn’t capture those missing translation on time and this block other team changes. Since the other teams do not know what exactly cause the problem, therefore, some are panic. Some try to fix the problem with some other workarounds. Major Cause of the Issues: Communication The main source of the issues is breakdown. communication Architecture on the translation is not handed over properly, to the successor team and entire engineering teams. Both the translation and RTL implementation details didn’t cascaded to all, causing unnecessary time spent on investigation and fixing it the wrong way. Fix it: Tell the World Tell everyone your changes and what they need to do. Channels like email, Slack, Skype etc. For my case, email is the most effective way, and slack in our engineering channel and pinned it. Communication Format Here are my thoughts on email format. Always short summary come first, then TL;DR, no one has time to read long email when they don’t need to. Summary — The best is less than 50 words. Keep it as short as possible. Objective — Why we do this, what are we trying to achieve, basically extension of the summary. Action needed and Details — What and how do you need people to involve in? Put a link to some details documentation if there is any. Here is an Example: Summary Moving forward, we will maintain all translations in , a tool for translation management. X START using the X for any current or future features that you are working on. Why Moving to X We have ambitious plan to go to the world. This mean that we need to be able to launch in new country faster. As part of the effort, we need to:- - Have a centralise translation management. Easier and faster for translator to add in new language for country launch. - Less or No developer involved in adding translation. Free developer to be more focus on building feature rather than adding translation. What You Need to Do The migration is in progress. YOU are part of it. I’ve added a section in README( ) on the code changes required. link here Take a look. Look for if you have any questions on that. core team names START using the X for any current or future features that you are working on. Documentation Format Straight to the point, can break it in to the Smaller picture (Implementation) and the Bigger Picture (TLDR, architecture changes). Maintain it in your sharing site, be it Share points, Confluence, or Github markdown. The Smaller Picture Summary — Can copy pasted the email summary or modified it to more technical as email might be including some stakeholders (delivery manager, product owners) but documentation focus solely on Developer. How old code looks like — Give an example on old code How the new code look like — Give an example on new code Captchas and Notes during development — Something to take note. TLDR — link to the bigger picture, architecture documentation (if any), or any external resources. Knowledge Sharing Session Conduct if required. To the team who need further details. Why it Matters? Confident and Mindful on Changes Make no one scare of touching your code. When bugs happens related to the changes, out of your office hours, the developers on the other side of the globe can pick it up. You don’t Want to Keep Working on the Same Sh*t Over and Over Again When there are new UI developed or developing by the other teams, you don’t want to RTL nor translate for them. Making sure they have enough knowledge on When to Communicate? Should it be done when you’ve completed the project? Or when you have a solution? It depends. For my case, we share with the teams when we have concrete and stable solution when we have about 70% of the pages are RTL-ed. But I think the communication can be done earlier, when we have about 30% pages converted, because at that point we have concrete solution already. Communication should be done as early as possible. To Whom You Should Communicate to? If you know the target team, send to them. In my case, the email is sent to all developers because translation and RTL is application wide. Who Should Get Communication Started? If no one is doing this in the company, don’t be afraid. YOU can be the one to start this. Don’t have the mindset of “I am just a developer” because these matters YOU. Do it when you think you need to. Talk to your leads, talk to your managers. I am glad I have a helpful and open lead that listen for feedback. And we did it. Email it out and slack it. The result is pretty encouraging I think. We have other team members start asking questions on the implementation; we have the co-worker who do the original POC wrote a detailed TLDR section (which some of it I didn’t know). This is good. Get the ball rolling! The End I don’t like lengthy email. I don’t dive in to lengthy documentation if I have no interest or not working on that. However, I would like to be aware of what should I take note. Documentation is boring too, so keep it short, write it the way you like to read. Knowing high level on what are the changes, what should I do and dive into details later whenever I need to. Communication is important. Cascading information effectively is important especially you have large team like that. Pick any means that work for you.
