diff --git a/contributor_docs/friendly_error_system.md b/contributor_docs/friendly_error_system.md index 28652be7b9..7cc3ecb2ed 100644 --- a/contributor_docs/friendly_error_system.md +++ b/contributor_docs/friendly_error_system.md @@ -6,15 +6,24 @@ The Friendly Error System (FES, 🌸) aims to help new programmers by providing The FES prints messages in the console window, as seen in the [p5.js Web Editor] and your browser JavaScript console. The single minified file of p5 (p5.min.js) omits the FES. - *We have an ongoing survey!* Please take a moment to fill out this 5-minute survey to help us improve the FES: [🌸 SURVEY 🌸] - [p5.js Web Editor]: https://editor.p5js.org/ -[🌸 SURVEY 🌸]: https://bit.ly/p5fesSurvey +## Lowering the Barriers to Debugging +The design of a tool should match the need of the people who will use it. As a tool that aims to lower the barriers to debugging, the design of FES is no exception. + +The best way to evaluate our existing design is to hear directly from people using p5.js. We ran a community survey in 2021 to gather feedback and future wishes for Friendly Errors. + +We believe the insights from our community members will be helpful for our contributors. You can see the results through the summary comic or the full report: +* [21-22 FES Survey Report Comic] +* [21-22 FES Survey Full Report] + + +[21-22 FES Survey Report Comic]: https://almchung.github.io/p5jsFESsurvey/ +[21-22 FES Survey Full Report]: https://observablehq.com/@almchung/p5-fes-21-survey ## Writing Friendly Error Messages -In this section, we will describe how you can contribute to the p5.js library by writing and translating error messages. +How to contribute to the p5.js library by writing and translating error messages? The FES is a part of the p5.js' [internationalization] effort. We generate all FES messages' content through [i18next]-based `translator()` function. This dynamic error message generation happens for all languages, including English - the default language of the p5.js. @@ -26,21 +35,24 @@ We welcome contributions from all around the world! 🌐 #### Writing Best Practices -FES message writers should prioritize lowering the barrier of understanding error messages and debugging. +FES message writers should prioritize lowering the barrier of understanding error messages and increasing the accessibility of debugging process. -Here are some highlights from our upcoming best-practice doc: +[Friendly Errors i18n Book] discusses challenges and best practices for writing friendly error messages within the cross-cultural i18n context. Here are some points from the book: -* Use simple sentences. Consider breaking your sentence into smaller blocks for best utilizing i18next's [interpolation] feature. -* Keep the language friendly and inclusive. Look for possible bias and harm in your language. Adhere to [p5.js Code of Conduct]. -* Avoid using figures of speech. Prioritize cross-cultural communication. -* Try to spot possible "[expert blind spots]" in an error message and its related docs. -* Introduce one technical concept or term at a timeβ€”link one external resource written in a beginner-friendly language with plenty of short, practical examples. +* Understand your audience: do not make assumptions about the audience of our error messages. Try to learn who is using our library and how they use it. +* Keep language inclusive. We strive to make error messages "friendly," what does it mean for you? Look for possible bias and harm in your language. Adhere to [p5.js Code of Conduct]. +* Use simple sentences whenever possible. Consider breaking your sentence into smaller blocks for best utilizing i18next's [interpolation] feature. +* Prioritize cross-cultural communication and provide a great experience across languages. Avoid using figures of speech. +* Introduce one technical concept or technical term at a time. Keep consistency in technical writing. Try to link one external resource written in a beginner-friendly language with plenty of short, practical examples. +[Friendly Errors i18n Book]: https://almchung.github.io/p5-fes-i18n-book/ [interpolation]: https://www.i18next.com/translation-function/interpolation [p5.js Code of Conduct]: https://github.com/processing/p5.js/blob/main/CODE_OF_CONDUCT.md#p5js-code-of-conduct [expert blind spots]: https://tilt.colostate.edu/TipsAndGuides/Tip/181 +[Friendly Errors i18n Book] is a public project, and you can contribute to the book through this separate [repo]. +[repo]: https://github.com/almchung/p5-fes-i18n-book #### Location of Translation Files `translator()` is based on i18next and imported from `src/core/internationalization.js`. It generates messages by looking up text data from a JSON translation file: diff --git a/translations/ko/README.md b/translations/ko/README.md index 4603f10aa9..c15844116f 100644 --- a/translations/ko/README.md +++ b/translations/ko/README.md @@ -1,15 +1,26 @@ # Welcome to the FES Korean branch! μ•ˆλ…•ν•˜μ„Έμš”, FES ν•œκ΅­μ–΄ λΈŒλžœμΉ˜μ— μ–΄μ„œμ˜€μ„Έμš”! -## ν•œκ΅­μ–΄ Translation Credits +## ν•œκ΅­μ–΄ 곡동 λ²ˆμ—­ κΈ°μ—¬μž Korean Translation Credits 2021λ…„ 가을뢀터 κ³΅λ™μž‘μ—…μœΌλ‘œ μ§„ν–‰λ˜μ–΄ 2022λ…„ 1월에 마무리된 FES μ—λŸ¬λ©”μ‹œμ§€ 곡동 λ²ˆμ—­ μž‘μ—…μ€ μ•„λž˜ 뢄듀이 ν•¨κ»˜ν•˜μ…¨μŠ΅λ‹ˆλ‹€. * [염인화](https://yinhwa.art/) (Inhwa Yeom): artist/XR researcher based in South Korea. (Take a look at her works on [p5 for 50+](https://p5for50.plus/) ([Processing Foundation Fellows 2020](https://medium.com/processing-foundation/p5-js-for-ages-50-in-korea-50d47b5927fb)) and p5js website Korean translation) * μ „μœ μ§„ (Youjin Jeon): artist/organizer based in Seoul, South Korea. [여성을 μœ„ν•œ μ—΄λ¦° 기술랩(Woman Open Tech Lab.kr)](http://womanopentechlab.kr/) and [Seoul Express](http://seoulexpress.kr/) * [μ •μ•Ž](https://www.almichu.com/) (Alm Chung, organizer): Korean-American artist/researcher based in Seattle, WA. * μ΄μ§€ν˜„ (Jihyun Lee): Korean publishing editor based in South Korea -## ν•œκ΅­μ–΄ Translation Resources -* μΆ”ν›„ 좔가될 μ˜ˆμ •μž…λ‹ˆλ‹€! +## μ˜ν•œ λ²ˆμ—­ λ¦¬μ†ŒμŠ€ (Korean-English Translation Resources) +* μ˜ν•œ [λ²ˆμ—­μ— 도움이 λ˜λŠ” 툴과 μœ μ˜μ λ“€]μž…λ‹ˆλ‹€. +* λ˜ν•œ μ˜ν•œ [λ²ˆμ—­ μž‘μ—… 쀑 λ§ˆμ£ΌμΉ˜λŠ” λ”œλ ˆλ§ˆλ“€] μ†μ—μ„œ 저희가 μ±„νƒν•œ 방식을 λͺ¨μ•„ μ μ–΄λ΄€μŠ΅λ‹ˆλ‹€. +* μ™Έλž˜ [기술 μš©μ–΄ 닀루기]에 λŒ€ν•œ λ…Όμ˜μž…λ‹ˆλ‹€. +* p5js μ›Ήμ‚¬μ΄νŠΈμ™€ 기술 λ¬Έμ„œμ—μ„œ μ‚¬μš©ν•˜λŠ” 기술 μš©μ–΄λ“€μ„ ν†΅μΌν•˜κΈ°μœ„ν•΄ μ‚¬μš©ν•˜κ³  있 [p5js.org/ko 기술 μš©μ–΄ 색인] μž…λ‹ˆλ‹€. +* ν˜„μ‘΄ν•˜λŠ” κ²€μƒ‰νˆ΄/λ²ˆμ—­ νˆ΄λ“€κ³Ό 연계 κ°€λŠ₯ν•œ "[사이λ₯Ό λ§΄λ„λŠ”]" λ²ˆμ—­λ¬Έμ— λŒ€ν•΄ μƒκ°ν•΄λ³΄λŠ” κΈ€μž…λ‹ˆλ‹€. +이 외에도 FES의 세계화 μž‘μ—… κ³Όμ •, 그리고 κ³Όμ • 쀑 λ…Όμ˜λœ μ΄μŠˆλ“€μ„ [Friendly Errors i18n Book ✎ μΉœμ ˆν•œ 였λ₯˜ λ©”μ‹œμ§€ 세계화 κ°€μ΄λ“œλΆ]μ—μ„œ 읽어보싀 수 μžˆμŠ΅λ‹ˆλ‹€. "μΉœμ ˆν•œ 였λ₯˜ λ©”μ‹œμ§€ 세계화 κ°€μ΄λ“œλΆ"은 μ˜€ν”ˆ μ†ŒμŠ€ ν”„λ‘œμ νŠΈμ΄λ©°, 이 [λ…λ¦½λœ λ ˆνŒŒμ§€ν† λ¦¬ (repository)]λ₯Ό 톡해 κΈ°μ—¬ κ°€λŠ₯ν•©λ‹ˆλ‹€. -μ§ˆλ¬Έμ΄λ‚˜ 건의 사항은 @almchung μ—κ²Œ λ¬Έμ˜μ£Όμ‹œκΈΈ λ°”λžλ‹ˆλ‹€. \ No newline at end of file + +[λ²ˆμ—­μ— 도움이 λ˜λŠ” 툴과 μœ μ˜μ λ“€]: https://almchung.github.io/p5-fes-i18n-book/ch4/#tools +[λ²ˆμ—­ μž‘μ—… 쀑 λ§ˆμ£ΌμΉ˜λŠ” λ”œλ ˆλ§ˆλ“€]: https://almchung.github.io/p5-fes-i18n-book/ch4/#dilemmas +[기술 μš©μ–΄ 닀루기]: https://almchung.github.io/p5-fes-i18n-book/ch3/ +[사이λ₯Ό λ§΄λ„λŠ”]: https://almchung.github.io/p5-fes-i18n-book/ch5/ +[Friendly Errors i18n Book ✎ μΉœμ ˆν•œ 였λ₯˜ λ©”μ‹œμ§€ 세계화 κ°€μ΄λ“œλΆ]: https://almchung.github.io/p5-fes-i18n-book/ +[λ…λ¦½λœ λ ˆνŒŒμ§€ν† λ¦¬ (repository)]: https://github.com/almchung/p5-fes-i18n-book \ No newline at end of file