Conversation
Start with a readme that documents the intents and goals of the project.
trimmed language, added TOC
| things in the way. | ||
|
|
||
| 1. Create a file in your project named `rax-docs`, and add the content | ||
| from https://github.com/IDPLAT/rax-docs/blob/master/rax-docs |
There was a problem hiding this comment.
I suggest using a defined hyperlink, not a bare address.
|
|
||
| After obtaining the toolkit via either `install`ing or `get`ting it, | ||
| you have to run `./rax-docs setup` to build your local dev | ||
| environment. This builds a Docker image locally to act as an isolated |
There was a problem hiding this comment.
...builds a local Docker image...
| environment. This builds a Docker image locally to act as an isolated | ||
| environment. | ||
|
|
||
| This toolkit is meant to feel very similar to the original. In general, |
There was a problem hiding this comment.
Add a header here, something like "Legacy Users" (should be line 81, apologies)
There was a problem hiding this comment.
My assumption going into this is that legacy users will be the (initial) primary group of users.
There was a problem hiding this comment.
| How it works | ||
| ============ | ||
|
|
||
| The goal of this toolkit is to make one tool that everyone can use to |
There was a problem hiding this comment.
This is kind of a run on. Can this be more succinctly said or split into two more more thoughts?
| as well as how they run commands to build, test, and publish their | ||
| docs. Build automaters such as Jenkins will also use it this way. | ||
|
|
||
| This wrapper script is the part of the project that is distributed |
There was a problem hiding this comment.
Personal preference, I'd replace 'This wrapper script' with rax-docs
| Testing and debugging | ||
| ===================== | ||
|
|
||
| There are bats tests for the script. For easier testing, there are a few |
There was a problem hiding this comment.
There's only one variable listed here, but "there are a few".
There was a problem hiding this comment.
| To fill this role, the wrapper script is only responsible for | ||
| retrieving the main body of the toolkit by cloning the repo from | ||
| GitHub. After cloning, it delegates all other commands to scripts in | ||
| the local, cloned directory. |
There was a problem hiding this comment.
I think grammatically you can omit the ,
| the local, cloned directory. | |
| the local cloned directory. |
There was a problem hiding this comment.
This is two adjectives describing the same noun. The comma is required.
There was a problem hiding this comment.
I always thought the rule was two describing adjectives didn't need the comma, but three-plus did.
There was a problem hiding this comment.
There was a problem hiding this comment.
This might actually sound better as
| the local, cloned directory. | |
| the locally cloned directory. |
There was a problem hiding this comment.
lol. i had the same thought: change an adjective to an adverb, and the problem goes away!
Testing became too tricky, even with the SOURCE_DIR option. I changed it to completely stub out git. This variable isn't needed anymore.
|
In the interest of getting a landing page out there for people to start looking at, I'm going to merge this. Feel free to point out additional changes that need to be made or open PRs. This was just a first draft and certainly still needs improvement. |
3 participants
Start with a readme that documents the intents and goals of the
project.