doc(readme): Add language in code section #1703
Conversation
In the whole of DigitalService we talked about our default for using German and English mixed in the code. We are already doing this hybrid approach in our codebase thoroughly. Mostly, we identified on a Digitalservice level, the risk that open-source contributors might not feel invited when they see a lot of German in the variable names. Therefore, we add an explanation in the readme for everyone to see. This will probably be used as a DigitalService-wide base, so very happy about your feedback!
README.md
Outdated
| @@ -284,6 +284,10 @@ In development mode, run the `npm run start:storybook` command. | |||
|
|
|||
| The `AIRLINE_FILE_PATH` corresponds to the file that contains airlines data that will be transformed into `json` via the `build:airlines-data ` task. For further details and access to the source, please reach out to the maintainers of this repository. | |||
|
|
|||
| ## Code Language Conventions | |||
|
|
|||
| This project uses a hybrid approach to language in code, mixing English and German. While technical implementation uses English (e.g., `function validateData()`), domain-specific terms are kept in German (e.g., `hasRechtsschutzversicherung: boolean`). This is crucial because many German administrative terms lack precise English equivalents, leading to inconsistencies and communication overhead when translated. This hybrid approach ensures clear communication with domain experts and maintains code readability within our specific context. While we acknowledge this might pose a barrier for non-German speaking contributors, we believe it's the most effective solution for our project. We encourage contributors to ask questions about any unfamiliar German terms. | |||
There was a problem hiding this comment.
I would suggest rewording the sentence:
...domain-specific terms are kept in German...
to:
We could keep domain-specific terms in German only if an appropriate English equivalent is not available.
Reason
Some German terms in the ZOV area can be easily translated, such as Verspätung (delay) or Annullierung (cancellation), and we are already using their English equivalents in the source code.
There was a problem hiding this comment.
Sounds logical to me to communicate this.
But maybe we can discuss this hybrid approach in the near future. I guess, this can lead in inconsistencies in naming conventions and mental overload for switching between german and english. From my perspective it is better to choose english as default. :)
There was a problem hiding this comment.
@aaschlote
I adapted it the following way:
...domain-specific terms are kept in German...
becomes:
...domain-specific terms can be kept in German...
to reflect that. Thank you for noticing this important distinction. :)
In the whole of DigitalService we talked about our default for using German and English mixed in the code. We are already doing this hybrid approach in our codebase thoroughly. Mostly, we identified on a Digitalservice level, the risk that open-source contributors might not feel invited when they see a lot of German in the variable names. Therefore, we add an explanation in the readme for everyone to see.
This will probably be used as a DigitalService-wide base, so very happy about your feedback!
(I will fix the style changes after your feedback)