You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contributor_docs/friendly_error_system.md
+23-11Lines changed: 23 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,15 +6,24 @@ The Friendly Error System (FES, 🌸) aims to help new programmers by providing
6
6
7
7
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.
8
8
9
-
*We have an ongoing survey!* Please take a moment to fill out this 5-minute survey to help us improve the FES: [🌸 SURVEY 🌸]
10
-
11
9
[p5.js Web Editor]: https://editor.p5js.org/
12
-
[🌸 SURVEY 🌸]: https://bit.ly/p5fesSurvey
13
10
11
+
## Lowering the Barriers to Debugging
12
+
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.
13
+
14
+
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.
15
+
16
+
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 Full Report]: https://observablehq.com/@almchung/p5-fes-21-survey
14
23
15
24
## Writing Friendly Error Messages
16
25
17
-
In this section, we will describe how you can contribute to the p5.js library by writing and translating error messages.
26
+
How to contribute to the p5.js library by writing and translating error messages?
18
27
19
28
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.
20
29
@@ -26,21 +35,24 @@ We welcome contributions from all around the world! 🌐
26
35
27
36
#### Writing Best Practices
28
37
29
-
FES message writers should prioritize lowering the barrier of understanding error messages and debugging.
38
+
FES message writers should prioritize lowering the barrier of understanding error messages and increasing the accessibility of debugging process.
30
39
31
-
Here are some highlights from our upcoming best-practice doc:
40
+
[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:
32
41
33
-
*Use simple sentences. Consider breaking your sentence into smaller blocks for best utilizing i18next's [interpolation] feature.
34
-
* Keep the language friendly and inclusive. Look for possible bias and harm in your language. Adhere to [p5.js Code of Conduct].
35
-
*Avoid using figures of speech. Prioritize cross-cultural communication.
36
-
*Try to spot possible "[expert blind spots]" in an error message and its related docs.
37
-
* 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.
42
+
*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.
43
+
* 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].
44
+
*Use simple sentences whenever possible. Consider breaking your sentence into smaller blocks for best utilizing i18next's [interpolation] feature.
45
+
*Prioritize cross-cultural communication and provide a great experience across languages. Avoid using figures of speech.
46
+
* 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.
`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:
2021년 가을부터 공동작업으로 진행되어 2022년 1월에 마무리된 FES 에러메시지 공동 번역 작업은 아래 분들이 함께하셨습니다.
6
6
*[염인화](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)
7
7
* 전유진 (Youjin Jeon): artist/organizer based in Seoul, South Korea. [여성을 위한 열린 기술랩(Woman Open Tech Lab.kr)](http://womanopentechlab.kr/) and [Seoul Express](http://seoulexpress.kr/)
8
8
*[정앎](https://www.almichu.com/) (Alm Chung, organizer): Korean-American artist/researcher based in Seattle, WA.
9
9
* 이지현 (Jihyun Lee): Korean publishing editor based in South Korea
10
10
11
-
## 한국어 Translation Resources
12
-
* 추후 추가될 예정입니다!
11
+
## 영한 번역 리소스 (Korean-English Translation Resources)
12
+
* 영한 [번역에 도움이 되는 툴과 유의점들]입니다.
13
+
* 또한 영한 [번역 작업 중 마주치는 딜레마들] 속에서 저희가 채택한 방식을 모아 적어봤습니다.
14
+
* 외래 [기술 용어 다루기]에 대한 논의입니다.
15
+
* p5js 웹사이트와 기술 문서에서 사용하는 기술 용어들을 통일하기위해 사용하고 있 [p5js.org/ko 기술 용어 색인] 입니다.
16
+
* 현존하는 검색툴/번역 툴들과 연계 가능한 "[사이를 맴도는]" 번역문에 대해 생각해보는 글입니다.
13
17
18
+
이 외에도 FES의 세계화 작업 과정, 그리고 과정 중 논의된 이슈들을 [Friendly Errors i18n Book ✎ 친절한 오류 메시지 세계화 가이드북]에서 읽어보실 수 있습니다. "친절한 오류 메시지 세계화 가이드북"은 오픈 소스 프로젝트이며, 이 [독립된 레파지토리 (repository)]를 통해 기여 가능합니다.
14
19
15
-
질문이나 건의 사항은 @almchung 에게 문의주시길 바랍니다.
20
+
21
+
[번역에 도움이 되는 툴과 유의점들]: https://almchung.github.io/p5-fes-i18n-book/ch4/#tools
22
+
[번역 작업 중 마주치는 딜레마들]: https://almchung.github.io/p5-fes-i18n-book/ch4/#dilemmas
0 commit comments