4 ms·
This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github
by danpalmer 10y ago
This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github.com/playframework/playframework/pull/6545 – tldr: not much.
I work a lot with Django, and the documentation is amazing. It's up to date, cross-referenced, everything is linked to everything else, code is executable, etc.
Here, rather than a 2 line fix to make the code in the examples executable and explain how some data is being used, the maintainers opt to keep the code examples non-executable, and obfuscate the code, expanding explanations in text to make up for it.
Documentation is important. If someone doesn't understand it, the project should make a sincere attempt to understand why, take on feedback, instead of shutting down discussion and dismissing someones lack of understanding.
- dozzie 10y ago> This pull request showed me just how much the Scala community values good documentation: https://github.com/playframework/playframework/pull/6545 https://github.com/playframework/playframework/pull/6545 – tldr: not much. Erm... But the change was shitty. How would that make good documentation? The phrase just before said "Here's example JSON", and the JSON got changed to Scala code. How is that indication of appreciation or not of good documentation?
- smallnamespace 10y agoNot to mention the same doc page already showed how to convert JSON into a Scala value earlier.
- merb 10y agowell if you work a lot with Django than you have the same stuff like that aswell: > https://docs.djangoproject.com/en/1.10/howto/initial-data/ https://docs.djangoproject.com/en/1.10/howto/initial-data/ > https://docs.djangoproject.com/en/1.10/topics/serialization/#xml https://docs.djangoproject.com/en/1.10/topics/serialization/... of course you can't just use it directly in Python. Documentation is about reading, 90% of the stuff is just reading. And there is clearly everything said about the snippet above the snippet: "In the code samples below, we’ll use the following JSON:". Since you already visited the last page, you should've probably already understood how to parse the Json. I see a lot of issue's on a daily basis and I even give some examples if needed, even if a discussion should take place on a mailing list, however I think before ANY issue should be made, people should carefully read and check if there is even an issue. But Playframework's documentation is already really good. There are some cases which aren't described so good, but they aren't even well described in Django I guess, what I mean is testing, a lot of this topic is not easy and you probably learn on your way of getting a better developer to get better in it. I started to contribute to Play! In the middle/start of the year and a lot of people are just helpful (and busy). And I've seen plenty of one character spelling mistakes merged. If something is not strictly understandable we even give a advice to discuss it on the mailing list.
- 0xmohit 10y agoI can't comment about the specific pull request, but the number of contributors is probably a reasonable indicator. Look at the number of contributors for Scala [0], Go [1], and Rust [2]. [0] https://github.com/scala/scala/ https://github.com/scala/scala/ [1] https://github.com/golang/go/ https://github.com/golang/go/ [2] https://github.com/rust-lang/rust/ https://github.com/rust-lang/rust/
- blacksmythe 10y ago>> number of contributors is probably a reasonable indicator In case you don't want to click on the links: Scala: 287 Go: 704 Rust: 1599