Document how to test ORCID login locally #5043
Conversation
ajrbyers
requested review from
StephDriver and
mauromsl
and removed request for
mauromsl
docs/md/orcid.md
Outdated
| ```py | ||
| ENABLE_ORCID = True | ||
| ORCID_CLIENT_SECRET = "your client secret" | ||
| ORCID_CLIENT_ID = "your client ID" |
There was a problem hiding this comment.
just a comment - but this made me wonder what syntax we have for showing things like 'your client secret' - one of the things I struggle with when looking at examples online is which part to replace - e.g.
"your client secret" or your client secret - much worse when it isn't obvious if it should be a string or not or snake/kebab case used within quotes etc.
I'm not saying this example here is unclear, more that it prompted me to think it would be good to have a standard syntax for replacable values.
There was a problem hiding this comment.
Yes, agreed. For now I will follow this: https://developers.google.com/style/placeholders
There was a problem hiding this comment.
I can work out what you mean, but I do think the documentation could be clearer.
The same syntax and context was used for examples, for commands to type verbatim and for terminal interactions where some parts were typed and others not.
I believe clear documentation reduces support requests, so I would prefer to have this documentation 'obvious' rather than 'needing to be worked out'. But we've not really had much discussion yet about documentation, standardising syntax etc, so I may be jumping ahead of the intention behind this work. So I am unsure whether it is for changes to be made now, or something to be considered further when we talk more about documentation.
docs/md/orcid.md
Outdated
|
|
||
| The following steps were written for Ubuntu, and are meant for testing the press site. | ||
|
|
||
| 1. Create a test client on orcid.org and enter a normal domain of your choosing (it won’t be accessed) with `http` and the Janeway port you use for development: `http://www.openlibhums.org:8000/` |
There was a problem hiding this comment.
would be good to have an example for completeness or is that the example? If so call it an example?
docs/md/orcid.md
Outdated
|
|
||
| ``` | ||
| 127.0.0.1 www.openlibhums.org | ||
| ``` |
There was a problem hiding this comment.
again, for clarity, label examples as examples.
docs/md/orcid.md
Outdated
|
|
||
| ``` | ||
| sudo systemctl restart NetworkManager | ||
| ``` |
There was a problem hiding this comment.
This looks like a command to be used as is, rather than an example, and for clarity this needs to be distinguished from the examples used above.
docs/md/orcid.md
Outdated
| python src/manage.py alter_domains press | ||
| Altering domain for Test A, current domain: localhost:8000 | ||
| Enter the new domain you wish to set: www.openlibhums.org:8000 | ||
| Altering domain record...... [Ok] |
There was a problem hiding this comment.
It is unclear here which parts are you typing, and which are prompts.
|
OK @StephDriver, I've given it a once-over for clarity with the help of your comments. |
No description provided.