Thanks for putting this pull request together! ⚡

There might be other places in the documentation where we use cURL and this mistake could be made. If we'd add a note like this, I think it would be helpful to put it in a more visible place, rather than in a specific article. What do you think?

Also, throughout the documentation -- only :user and <user> are used when referring to placeholders/parameters that should be replaced with a concrete value. I'd love to know what you think could be improved in the documentation (in general) so that we don't need to clarify this in specific articles (which would add noise). Would it be helpful if this was clarified somewhere on the API V3 homepage, possibly here: http://developer.github.com/v3/#parameters ?

Ivan,

I didn't expect such a fast response! Nice side-effect of having people in
many time zones.

I'm having a hard time extrapolating from my own newb mistake to the
mistakes that others can make. I never came in through the "front door" of
the documentation and missed the V3 homepage. I had a one-off need to use
the API and came in from
http://developer.github.com/v3/auth/#basic-authentication and
https://github.com/settings/applications .

Its a tough problem. You'd want the examples to be both explicit and
templatized at the same time. In other words, in this command:

curl -u 3816d821c80a6847ca84550052c1ff6246e8169b:x-oauth-basic
https://api.github.com/user

you'd want 3816d821c80a6847ca84550052c1ff6246e8169b to look like
":yourTokenHere" and yet not mess up the literal :x-oauth-basic that is
after the token. Maybe instead of wrapping them in

 the examples could

be 
 tags with pre-like styling so you could italicize the portions to

be replaced. As it is, I had to replace the 381... token but not replace *

/user* - which is a bit confusing.

As to making it consistent and not repeating it - it all depends on where

someone comes from so I'd err on the side of stating it too often.
hope this helps,

JohnB
On Mon, Oct 21, 2013 at 3:17 AM, Ivan Žužak notifications@github.comwrote:

Thanks for putting this pull request together! [image: :zap:]
There might be other places in the documentation where we use cURL and

this mistake could be made. If we'd add a note like this, I think it would

be helpful to put it in a more visible place, rather than in a specific

article. What do you think?
Also, throughout the documentation -- only :user and  are used when

referring to placeholders/parameters that should be replaced with a

concrete value. I'd love to know what you think could be improved in the

documentation (in general) so that we don't need to clarify this in

specific articles (which would add noise). Would it be helpful if this was

clarified somewhere on the API V3 homepage, possibly here:

http://developer.github.com/v3/#parameters ?
—

Reply to this email directly or view it on GitHubhttps://github.com/github/developer.github.com/pull/330#issuecomment-26705895

.


https://twitter.com/JohnB

http://github.com/JohnB

http://JohnBaylor.org/

I never came in through the "front door" of the documentation and missed the V3 homepage. I had a one-off need to use the API and came in from http://developer.github.com/v3/auth/#basic-authentication and https://github.com/settings/applications .

That's a great point! I'll give this some more thought.

curl -u 3816d82:x-oauth-basic https://api.github.com/user

I think that some of the curl examples are not as clear as they could be, as you noticed. I'll close this pull request make another one to try and clear them up, using the general idea you suggested. Thanks for the helpful pointer!

🚤