Create Vane Documentation

Worker(s): ~tinnus-napbus Reward: 5 Stars WIP

Overview

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.

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).

Scope

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.

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:

Here's a sketch of what's probably needed for each vane in order of priority:

1) clay

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 doc), but much of it is too dense.

For clay we want:

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 which you can use.

2) eyre

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 that needs to be brought through to completion.

For eyre we want:

3) iris

Iris has no explanation whatsoever, but does have an API reference.

For iris we want:

4) jael

Jael has no explanation whatsoever, but does have an API reference.

For jael we want:

5) behn, dill, ames

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.

Adding more documentation to these vanes is lowest priority, but if you have ideas for contribution they'd be welcome.

Requirements/Resources

Work should be submitted as pull requests against the docs repository, and is to be considered complete upon review and merge.

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.

Compensation

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: