git.iko.soy/urbit.org
on master help sign in
Create urbit-react-docs.md
bbadb25alangalis
content/grants/2023/urbit-react-docs.mdnew file+124
compare with master
unifiedsplit
@@ -0,0 +1,124 @@
1++++
2+
3+title = "Modernize Urbit React Developer Documentation"
4+date = "2022-02-23"
5+
6+[taxonomies]
7+grant_type = ["Proposal"]
8+grant_category = ["Documentation"]
9+
10+[extra]
11+image = ""
12+description = "Modernize Urbit React Developer Documentation"
13+reward = "1 Star"
14+assignee = ["~sidnym-ladrut"]
15+champion = ["~lagrev-nocfep"]
16+grant_id = "P0242"
17+completed = false
18+canceled = false
19+
20++++
21+
22+## Rationale ##
23+
24+
25+
26+The front-end React examples provided in Urbit's developer documentation (i.e. the ["Chat Lightning Tutorial"][ex-1] and ["App School II: Full-Stack"][ex-2] pages) use legacy, class-based React patterns that have largely been phased out over the past few years in favor of [modern, hook-based React style][re-hook]. These examples should be refactored to use this modern style to improve the developer onboarding experience (as increasing amounts of [React learning materials use hooks][re-tut]) and future-proof the material presented (as the official React documentation eventually migrates to [primarily present the modern style][re-docs]).
27+
28+
29+
30+## Overview ##
31+
32+
33+
34+The content for the Urbit React examples is split across two repositories:
35+
36+
37+
38+1. [urbit/doc-examples][git-ex]: Contains the source code for the React examples.
39+
40+2. [urbit/developers.urbit.org][git-org]: Contains the web-hosted documentation for the React examples, which can be viewed at [developers.urbit.org](developers.urbit.org).
41+
42+
43+
44+Within these repositories, the content associated with the following examples needs to be updated to the modern React style:
45+
46+
47+
48+1. ["Chat Lightning Tutorial"][ex-1]: Will require edits primarily in the source references, particularly those in the ["Additional commentary" section][ex-1-edit].
49+
50+2. ["App School II: Full-Stack"][ex-2]: Will require nearly a full rewrite, though many source references will look similar.
51+
52+
53+
54+## Features in scope ##
55+
56+
57+
58+- Refactor the ["Chat" example][git-chat-src] to replace React classes with React hooks wherever possible.
59+
60+- Refactor the ["Journal" example][git-jour-src] to replace React classes with React hooks wherever possible.
61+
62+- Revise the ["Chat Lightning Tutorial"][git-chat-doc] documentation to update source references and add commentary to any new and nontrivial references.
63+
64+- Rework the ["App School II: Full-Stack"][git-jour-doc] documentation to explain the flow and key operations (i.e. peeks, pokes, and subscriptions) of the refactored React "Journal" code.
65+
66+
67+
68+## Implementation Notes ##
69+
70+
71+
72+The refactored React examples will take architectural inspiration and library
73+
74+cues from popular React applications in the Urbit ecosystem (e.g. [`%landscape`][git-landscape] and [`%sphinx`][git-sphinx]) to further improve their utility for learning developers.
75+
76+
77+
78+## Milestones and Compensation ##
79+
80+
81+
82+The grantee will receive 1 star upon fulfillment of this grant.
83+
84+
85+
86+
87+
88+[git-ex]: https://github.com/urbit/docs-examples
89+
90+[git-org]: https://github.com/urbit/developers.urbit.org
91+
92+[git-chat-src]: https://github.com/urbit/docs-examples/blob/main/chat-app/react-frontend/src/App.jsx
93+
94+[git-chat-doc]: https://github.com/urbit/developers.urbit.org/blob/main/content/guides/quickstart/chat-guide.md
95+
96+[git-jour-src]: https://github.com/urbit/docs-examples/blob/main/journal-app/ui/src/App.js
97+
98+[git-jour-doc]: https://github.com/urbit/developers.urbit.org/blob/main/content/guides/core/app-school-full-stack/7-app-logic.md
99+
100+[git-landscape]: https://github.com/tloncorp/landscape-apps
101+
102+[git-sphinx]: https://github.com/arthyn/sphinx
103+
104+
105+
106+[re-hook]: https://reactjs.org/blog/2019/02/06/react-v16.8.0.html
107+
108+[re-tut]: https://beta.reactjs.org/learn/tutorial-tic-tac-toe
109+
110+[re-docs]: https://beta.reactjs.org/
111+
112+
113+
114+[ex-1]: https://developers.urbit.org/guides/quickstart/chat-guide
115+
116+[ex-1-edit]: https://developers.urbit.org/guides/quickstart/chat-guide#additional-commentary
117+
118+[ex-2]: https://developers.urbit.org/guides/core/app-school-full-stack/7-app-logic
119+
120+[ex-2-get]: https://developers.urbit.org/guides/core/app-school-full-stack/7-app-logic#getting-entries
121+
122+[ex-2-sub]: https://developers.urbit.org/guides/core/app-school-full-stack/7-app-logic#subscription
123+
124+[ex-2-add]: https://developers.urbit.org/guides/core/app-school-full-stack/7-app-logic#add-edit-delete