Look into multilingual support for documentation site about cht-docs HOT 13 CLOSED

Here's where we're at. @MaxDiz / @abbyad will you take a look and let me know what you think?

https://docs.google.com/document/d/1SotCVPTBtPfDodcjZvrQ3qC5e97yunwnRlnT6EENJF4/edit?usp=sharing

from cht-docs.

When a developer makes a change that requires documentation, or we discover deficiencies in existing documentation, the docs get updated, in English.

So then, if we are going to have documentation in different languages we need to also create a system whereby the non-English versions keep up to date. I would presume that it's better to have only English vs. your native language but wrong / out of date (but to be clear this is a guess: I only speak English and so don't have a useful opinion).

As far as I'm aware we currently have issues keeping the app translated, so I imagine us working out a flow for that would also allow us to work out a flow for this.

from cht-docs.

updated issue to prioritize the documentation site for initial exploration

from cht-docs.

@MaxDiz @SCdF

Since I’m new to this effort, I want to start by further understanding the requirements. Just want to get a sense of the ballpark so we can figure out what tradeoffs to make, so not having definitive answers to these is ok.

• What is the current workflow for translation, and which languages are supported?
• Are there user types aside from developers that will be reading these docs?
• How many pages of documentation are we talking about, roughly speaking?
• Is it an all-or-nothing deal or are some docs more critical to keep updated than others?
• What is the maximum amount of monthly budget that can be spent on a potential service?
• What is the maximum amount of on-going manual effort that can be spent by a Medic obtaining translations / QAing the result / updating the site?
• What is the maximum amount of upfront developer time that can be spent integrating a potential service?
• What is the minimum acceptable level of accuracy that these translations can have? E.g. is a Google Translate level of accuracy acceptable?

from cht-docs.

Hi @fourestfire. Good questions. We're in the early stages of exploration of this functionality, so I will provide as much guidance as I can:

What is the current workflow for translation, and which languages are supported?

We currently only support english and do not have translation capabilities. Any translation we do currently is 1-off and manual (or supported by google translate based on individual preferences)

Are there user types aside from developers that will be reading these docs?

Summary of user types for the documentation site:
End users - covers the purpose of CHT features together with instructions and explanations of how to perform tasks such as data entry, import and export of data, reporting, and other topics related to the usage of the software. It is meant for CHWs and Supervisors.
Implementing partners - aims to provide support for the installation, maintenance, project reporting, and interoperability of the CHT platform. Subjects include infrastructure management, application deployment, impact analytics, and integration with complimentary systems. It is meant for project implementers.
App builders - offers detailed information on application configuration options, workflow digital translation, meta-data set-up, and analytics management. It is focused on application administrators.
Data scientists - provide information on data warehousing, sharing, and harmonization. It is focused on data managers and analyzers, as well as researchers.
Developers and Designers - provides a detailed description of the CHT core code contribution guidelines, design guidelines, API’s, system architecture, as well as the Android Software Development Kit. It serves as essential resources for developers and designers building upon the CHT platform.

How many pages of documentation are we talking about, roughly speaking?

depends how we break up the index. Probably in the range of 25 - 50 pages.

What is the maximum amount of monthly budget that can be spent on a potential service?

budget has not been set yet. We are looking to gain a better understanding of options before funding is considered. If you can include ballpark cost estimates in your analysis, it would be helpful.

What is the maximum amount of on-going manual effort that can be spent by a Medic obtaining translations / QAing the result / updating the site?

Our experience currently is that translations require too much effort to get done on a regular schedule. If you can help to provide guidance on expected manual effort as part of your analysis of different tools, we can socialize within the Org to get a feel for available team time allocation vs cost of 3rd party tool, etc

What is the maximum amount of upfront developer time that can be spent integrating a potential service?

This functionality has been identified as a need by multiple deployment partners and projects and would need to be prioritized among all of our other work. It would be great if you can help us to understand ballpark effort level for potential solutions (T-shirt sizing would be sufficient)

What is the minimum acceptable level of accuracy that these translations can have? E.g. is a Google Translate level of accuracy acceptable?

We generally aim for professional level of communication. It sounds like there may be some trade-off between cost and quality. It would be helpful if you can include translation quality in your analysis of solution options

from cht-docs.

Thanks Max!! Appreciate the detail on this.

from cht-docs.

currently blocked by tooling choice. @fourestfire we will add questions or comments to your working doc as they come up. Thanks again for putting such a solid assessment together!

from cht-docs.

Hi @fourestfire on today's squad team call, we discussed bumping translations to our next round of doc site improvements. The squad felt our best approach would be to gain user feedback from the initial site launch (primarily information quality reviews and which pages need translated) before investing additional resources. You're assessment will make it much easier for us to pick this issue back up in a couple of months. Thank you!

from cht-docs.

transferring to new cht-docs repo

from cht-docs.

Hugo, which we are now using for generating the doc site has multi-lingual support. Can we close this issue now, and revisit if/when we want to translate certain sections?

from cht-docs.

Hugo sounds like a good native option.
I'd like to have a concrete decision on approach before closing the issue. We can delay until there is a clear partner need.

from cht-docs.

I think our approach is to use Hugo pages for translations when we need it. I don't think there is anything more to decide on right now since we are not considering translating the entire documentation site at this time.

from cht-docs.

ok by me

from cht-docs.