Hexdocs - package docs in Portuguese?

Questions / Help
1

This is a question about style (not substance), and maybe the forum category is not the best one, but I couldn’t find one that fits better.

I’m writing an API client for a Portuguese payment gateway (euPago). Its main feature is the support for some very specific payment methods that can’t be used outside Portugal.

I don’t think non-Portuguese speaking developpers will be very interested in using this API (the API endpoints even use Portuguese words for the SOAP actions and parameters). For this reason, I’ve thought of documenting my package in Portuguese instead of English.

Portuguese is a better fit for the target users, but English brings the code and docs to a wider audience. And it’s possible that there might be some rule I’m not aware of that forbids non-English docs at hexdocs.

What is the ‘elixir way’ in this case?

1 Like
2

There is no rule against this, you can write your code and documentation in the language you want.

3

I would generally avoid doing documentation in anything but English. Even though it may be completely useless to use the system outside of Portugal, it’s entirely possible to have international engineers working with the system.

Storytime! I once worked on a project for a TV station in the Netherlands. The project was quite interesting and code quite good, what was quite extraordinary was that the project had a lot of documentation - probably the most I’ve ever seen. The only problem - it was all in Dutch. Not only the documentation was in Dutch, but all the comments in the source code and the entire user interface were in Dutch as well. After working with this project, I decided never to use Polish in my programming, so that nobody has to go through something like this.

5 Likes
4

You’re probably righ, and one day internarional developppers might want to work with this. I’ll document it in English.

5

You also have to consider that there can be developers that do not know English.

6

Is there the possibility of make two versions, one in English and another in Portuguese? Nothing related with software documentation, but with Dutch, I worked as a hardware technician for Philips and docs in English and Dutch are always available, sometimes I used to take the Dutch just to quickly put aside in favor of the English version.

7

That’s an interesting idea. I could host the English version at hexdocs and host a portuguese version somewhere else. It’s a lot more work, though… I’ll probably just stick with the English one xD

8

I admit I hadn’t even thought of that possibility. I wonder if there is a single non-english speaking elixir dev, though. With all documentarion I’m aware of being in English it must be no easy task.

The reason I thought of writing the docs in Portuguese was because the original API docs are in Portuguese. In my code, all the comments are all in English, though. It’s hard for me to imagine commenting code in Portuguese with so many english words or abbreviations (defmodule, type, if, else, unless, do, end, etc.).

9

Thanks everyone for your opinions and experiences. Based on what you’ve said, I guess it makes more sense to write the docs in English.

It’s completely possible that foreign companies might want to integrate with Portuguese payment methods and that the programmers at such companies won’t understand the Portuguese docs (even if someone else at the company speaks Portuguese)