PL Internationalization for Accessibility & ensuring Genericity

[tothambrus11]

Hi, I read the chapter on contracts a couple days ago, and I'm hugely impressed by this work. Super good arguments, clear flow and just sufficient redundancy for understanding tricky topics (though that's largely subjective).

Here are my initial comments that I noted down assuming I'm a developer with C++ and TypeScript experience:

"make stored properties private or private(set)"

-> clarify what private(set) means - it may not be evident, and people are generally lazy to read the appendix first

"Swift.min(xs.count, ys.count)"

-> is it useful to spell out Swift.min here instead of min?

"IDEs and documentation extractors recognize special /// comment syntax to provide an improved developer experience."

-> this is language specific, some languages only support the /** ... */ style, and some use no-op string literals in function bodies (Python). Maybe it could be phrased with e.g..

Since unfortunately Swift is orders of magnitudes less well-known for programmers, it may be an unnecessary burden / filter for readers if the book is in a language they don't already know. Swift is very easy to learn, but to a great extent, the contents of the book is exploring ideas that are important regardless of programming language. I am wondering if it could be useful (after the content itself is ready) to translate the book's language-specific parts into the most popular languages (C++, C#, Java, Rust, Typescript, Python + type hints). It may be a good selling point if the book is "customized" for you, so that

• a) the ideas can reach a wider - and initially less motivated - audience;
• b) readers love the book even more, because it's sort of personalized for them.

I would by no means suggest to use any other language than Swift to use for the writing process, but it may be interesting to keep in mind if some ideas couldn't be applied the same way to other languages. One such case is probably going to be concurrency, where each language has their set of concurrency models, but in such cases I assume you anyways either diversify or abstract away differences in a way that doesn't involve overfitting on the Swift model.

For the maintainable editing of the translations, probably existing internationalization features already present in mdbook would be sufficient, but the practical details can be figured out later.

Translation may also be a strong feedback mechanism: we need to get a language expert in each language who read the book's Swift version, and understand it well, to be able to translate the language-specific details in a way it makes sense for them. If they don't feel like aggreeing some idea is fully accurate/beneficial for their language, or if they have some additional thoughts while engaging with the content deeply during translation, you could gather feedback from a diverse range of experts, who may point out some phrasings wouldn't make sense for their community without providing more context/background. Even better, you can ask 2-3 people for each language to do the translation, and let them argue about the differences.

[dabrahams]

-> clarify what private(set) means - it may not be evident, and people are generally lazy to read the appendix first

Lots about Swift may not be evident to readers who don't know it and we'll need to decide what warrants explanation inline. My sense is that this one doesn't; the larger point is to protect invariants from being disturbed by clients, and I think that communicates well without an explanation even if you don't know Swift.

-> is it useful to spell out Swift.min here instead of min?

Yes because in the context of a sequence method, plain min means something else.

-> this is language specific

Yes, we chose to write in terms of a single language a book that can be generalized to other languages. I think we made it clear how to generalize this with “IDEs and documentation extractors recognize….” If we try to account for other languages everywhere the writing will become incredibly burdened. I believe versions of the book written in tersm other languages (particularly Rust) will be needed eventually.

Your ideas about the translation process are interesting. I hope we can explore them when the book finally reaches that stage.

Leaving open for that purpose.

[tothambrus11]

Thanks for the response, good points!