Reorganizing Odin Developer Documentation #133
Conversation
rmonnet
added
x:action/improve
|
@glennj, I started working on the CONTRIBUTING.md. The existing README contained material on how to contribute and how to build exercises. I split that out, with the contribution material going in the CONTRIBUTING.md and the how to build material going in its own file. I am stopping for the night and it is probably too early to review in detail but can you take a look at the structure (the level 2 and 3 headers and the split between documents) and give me your opinion. If this isn't clearer than what we have, I am ready to throw it out and consider it a prototype so don't hesitate to provide constructive criticism. |
rmonnet
changed the title
rmonnet
changed the title
rmonnet
changed the title
|
I haven't started reading the text, but the organization looks good. |
|
Okay, I'll keep going. For documentation, I have to put it on paper, leave it alone for a few days and then look at it again to see if it still make sense. I am going through other github repos to see what they are doing and stealing good ideas. |
Move How to build an exercise out of the main README, this makes the main README more of a map on where to find information. Start a Contributing Guide discussing how to use the forum, read and post issues for bug reports, suggestions, contributing documentation and contrinuting exercises. This needs additional eyes to see if it is going in the right direction. The How to Contribute an Exercise document may be slightly out of date since we have made quite a few changes to the tooling recently. This is next on the list to be reviewed.
Broke down FAQ.md into individual docs, each focus on answering a single question, the FAQ.md itself now just contains a little bit of introduction and a TOC pointing to the different FAQS. Reintegrated the content of the old README that was too detailed into new FAQS.
Last edit of the new and improved developer documentation.
|
Okay, I reviewed and edited all the developer documentation. We should now have a CONTRIBUTE.md, a README.md that points to other documents and focused FAQ documents. @glennj, can you review? |
There was a problem hiding this comment.
This file is centrally provided, and if it changes it will be pushed out to all tracks. No need to edit it.
There was a problem hiding this comment.
I was checking the links and the one at the bottom didn't link to a proper page so I changed it but I agree with your comment. Reverting back to the official version.
| @@ -1,14 +1,17 @@ | |||
| # The Odin Track Tools | |||
|
|
|||
| Note: in the text below, `$EXERCISM_ODIN` refers to your local copy of the Exercism Odin repository, see [How to Setup your Machine to Contribute to the track][how-to-setup-your-machine-to-contribute-to-the-track] for details. | |||
There was a problem hiding this comment.
| Note: in the text below, `$EXERCISM_ODIN` refers to your local copy of the Exercism Odin repository, see [How to Setup your Machine to Contribute to the track][how-to-setup-your-machine-to-contribute-to-the-track] for details. | |
| Note: in the text below, `$EXERCISM_ODIN` refers to the directory of your local copy of the Exercism Odin repository, see [How to Setup your Machine to Contribute to the track][how-to-setup-your-machine-to-contribute-to-the-track] for details. |
| Here is a brief description of the tools you will find in `$EXERCISM_ODIN/bin`: | ||
|
|
||
| - `bin/configlet` is the exercism tool, the options include: | ||
| - `bin/configlet` is the official Exercism tool, its options include: |
There was a problem hiding this comment.
| - `bin/configlet` is the official Exercism tool, its options include: | |
| - `bin/configlet` is the official Exercism track maintenance tool, its options include: |
|
This is great stuff. |
|
One other thing that might be interesting to add somewhere -- the track statistics. Select "Track Build Status" in the track dots menu Then click on "$N active practice exercises". That shows stats about each practice exercise: attempts, completions, number of test runs per attempt etc. We can monitor that to see if any particular exercise has a low completion rate -- it is too hard, does it need more instructions, etc. |
|
One other thing that might be interesting to add somewhere -- the track statistics. I didn't know about this feature but it is really cool. I added a FAQ to describe how to access it. |
In addition, added a new FAQ document to show how to access the track status.
2 participants
Move How to build an exercise out of the main README, this makes the main README more of a map on where to find information.
Start a Contributing Guide discussing how to use the forum, read and post issues for bug reports, suggestions, contributing documentation and contrinuting exercises.
This needs additional eyes to see if it is going in the right direction.
The How to Contribute an Exercise document may be slightly out of date since we have made quite a few changes to the tooling recently. This is next on the list to be reviewed.