Update Documentations #263
Conversation
prokarius
changed the title
docs/UserGuide.adoc
Outdated
| `e/`: `PERSON'S EMAIL` + | ||
| `b/`: `BIKE NAME` to be rented + | ||
| `lr/`: `RATE` of the loan, in dollars per hour + | ||
| [`t/`: `TAGS`] (Optional) + |
There was a problem hiding this comment.
This part is not formatted consistently with the command above (addbike). May I suggest standardising it to
n/NAME: The customer's name.
[t/TAGS]: Optional tags to tag the loan with.
etc.?
There was a problem hiding this comment.
I think this is OK, because it tells you the value of what each prefix is expecting though.
The addbike one had:
n/: BIKE NAME, which is consistent to this one.
There was a problem hiding this comment.
I think we should not format things like BIKE NAME, since it's not a code term and especially if it's inconsistent with the name used in the Format specification (like e/EMAIL in the Format specs vs e/:PERSON'S EMAIL in the Parameters specs). I think it's good to separate the technical names from the explanations as well (e.g. make a distinction between Bike and bike; one is a technical name, the other is plain English). Hence my suggestion, to make things clearer by using similar conventions.
There was a problem hiding this comment.
OK, you raise a good point. I have fixed this issue.
docs/UserGuide.adoc
Outdated
| @@ -217,12 +257,19 @@ Examples: | |||
| Set the password of the app to `n3wP4sS`. | |||
| // end::setpass[] | |||
|
|
|||
| [big red]#List of Parameters#: | |||
|
|
|||
| The old and new passwords of the application. + | |||
There was a problem hiding this comment.
This doesn't follow the format established for the other commands.
Try using:
CURRENT_PASSWORD: The old password of the application.
NEW_PASSWORD: The new password.
There was a problem hiding this comment.
I don't want to do it this way because some people might think that these are prefixes.
Hence the very different presentation.
There was a problem hiding this comment.
I would still prefer having a consistent format for everything (i.e. always have a list for the list of parameters), to make it easy for the reader to reference information.
I'm having an idea that in the preface, we can specify the format we're using to signify what should be typed into the command and what should be replaced by the reader's own data. Since the distinction matters a lot and we've actually taken it for granted thus far. e.g. We'll say "All parts of the command that are typed in CAPITAL_LETTERS_WITH_UNDERSCORES are parameter data to be filled in by your particular circumstance."
There was a problem hiding this comment.
OK, I have revised this.
docs/UserGuide.adoc
Outdated
| [big red]#List of Parameters#: | ||
|
|
||
| The old and new passwords of the application. + | ||
| Note that you only need to use spaces to seperate the two passwords. There is no prefix for this command! |
There was a problem hiding this comment.
Could be in a "Note" block
docs/UserGuide.adoc
Outdated
| @@ -372,21 +451,35 @@ Examples: | |||
| * `setemail default \new_email@gmail.com` | |||
| * `setemail \old_email@gmail.com \new_email@gmail.com` | |||
|
|
|||
| [big red]#List of Parameters#: | |||
|
|
|||
| The old email that you have set to the current one that you would want to use. + | |||
There was a problem hiding this comment.
Same comments as for setpass command
…into add-tips-in-ug
…10-2/main into add-tips-in-ug
Add list of params to functions in UG
Fix Issue #204