@@ -0,0 +1,95 @@
2+title = "Create Vane Documentation"
5+grant_type = ["bounties"]
6+grant_category = ["Documentation"]
9+description = "Create vane documentation for clay, eyer, iris, jael, and behn"
11+assignee = "~tinnus-napbus"
14+work_request_link = "https://airtable.com/shr4qt9t9kz7RaOIa?prefill_Grant+ID=B0025&prefill_Grant+Name=Create%20vane%20Documentation"
19+Creating and maintaining great documentation is an ongoing challenge for any project, ours included. The importance of documentation for Urbit is greater than most projects though, since so much of what we're doing is entirely novel.
21+This grant will have you work within the Urbit Foundation and Tlon to improve/create select portions of our documentation over the course of three months (April, May and June).
25+The goal over these three months is to more fully document Arvo's vanes. At present, the documentation is sporadic: some vanes have good TODO:[explanation-style] () documentation, others have good TODO:[API References] ()—some even have both. In the case of `eyre` and `clay`, which are arguably two of the most important vanes, we have neither—the explanations are outdated and overly technical, and the API reference is missing, incomplete, and outdated.
27+Your task is to fill in the blanks and provide complete documentation that leaves the reader with an understanding of *how to use the vanes.* Understanding *how they work* is of secondary importance, so:
29+- Explanations should be high level and light-to-free of code. The explanation should also serve to provide an overview of what kinds of capabilities the vane has in the first place.
30+- API reference for each vane should be complete
31+- Usage guides for common tasks would be very helpful
33+Here's a sketch of what's probably needed for each vane in order of priority:
35+### 1) [clay](https://urbit.org/docs/arvo/clay/clay)
37+The clay documentation is generally out of date, and the explanations are overly geared at describing how the internals work over what the interface is and what you can do with it. Some of the explanatory material is actually pretty good (like the [Architecture](https://urbit.org/docs/arvo/clay/architecture/) doc), but much of it is too dense.
41+* Proper API Reference documentation
42+* Guides for common tasks and capabilities
43+* Updated explanations of the key concepts and capabilities that [avoid becoming overly technical](https://urbit.org/docs/arvo/clay/local-reads/)
45+A contributor (~sovmep-ripsum) has recently been doing a lot of work on Clay and has offered to give you some direction on this, which will be helpful coming from the perspective of someone who's recently had to learn clay. He also wrote up some [notes](https://docs.google.com/document/d/10b5oC_Jcdq7Ex4iwf0mRjquEfolmUQvbs5YFJulsXa0/edit?ts=606cddf2) which you can use.
47+### 2) [eyre](https://urbit.org/docs/arvo/eyre/eyre/)
49+The eyre documentation is completely out of date and needs to be rewritten, particularly where the explanation is concerned. Fortunately, you're not starting from scratch with the API documentation, for which there's an [open PR](https://github.com/urbit/docs/pull/981) that needs to be brought through to completion.
53+* Complete API Reference documentation
54+* Guides for common tasks and capabilities
55+* Explanations of key concepts and capabilities
57+### 3) [iris](https://urbit.org/docs/arvo/iris/)
59+Iris has no explanation whatsoever, but does have an API reference.
63+* Explanations of key concepts and capabilities
64+* Guides for common tasks and capabilities
66+### 4) [jael](https://urbit.org/docs/arvo/jael)
68+Jael has no explanation whatsoever, but does have an API reference.
72+* Explanations of key concepts and capabilities
73+* Guides for common tasks and capabilities
75+### 5) [behn](https://urbit.org/docs/arvo/behn/behn/), [dill](https://urbit.org/docs/arvo/dill/dill), [ames](https://urbit.org/docs/arvo/ames/ames)
77+These vanes already have either minimal but viable explanations (behn, dill) or very good explanations (ames). They've all also got API Reference docs. None of them have usage guides that demonstrate how to work with the APIs though.
79+Adding more documentation to these vanes is lowest priority, but if you have ideas for contribution they'd be welcome.
81+## Requirements/Resources
83+Work should be submitted as pull requests against the [docs](https://github.com/urbit/docs) repository, and is to be considered complete upon review and merge.
85+You'll work with the Director of urbit.org and the Tlon docs team regularly, and should expect to meet weekly or biweekly to check in and share progress. Access to Tlon's infrastructure engineers will be provided for whenever you have technical questions.
89+We're targeting a three month period to complete the above, but may seek to extend the engagement. During this time, compensation is as follows:
91+* One star for completion of clay docs
92+* One star for completion of eyre docs
93+* One star for completion of iris and jael docs
94+* One star upon completion of all of the above docs
95+* One additional star awarded at the director's discretion for exemplary work