@aeros167 Thanks for the review. I have applied some of your suggestions.

• use variables <x> consistently.

I don't think this is a good idea. Examples helps readers than variables sometime.

For example, "Your Name" looks more clear than "<your name>". It is easy to understand that I should write "Inada Naoki", not "<inada naoki>" or "methane".

@methane

I don't think this is a good idea. Examples helps readers than variables sometime.

For example, "Your Name" looks more clear than "". It is easy to understand that I should write "Inada Naoki", not "" or "methane".

In that case, I think we should aim to consistently use one format or the other within the article, as switching between the two could cause some degree of confusion. I'm okay with using quotes instead of tags though.

Another alternative would be to use italics, that format is used commonly in a number of different areas of documentation to tell the reader that they should insert their own value:

git config --global user.name "Your Name"

In that example, the quotation marks have a functional purpose (telling git to treat it as a single argument even with the spaces).

In that case, I think we should aim to consistently use one format or the other within the article, as switching between the two could cause some degree of confusion.

I don't think it causes real confusion. Variables are useful when the same word is used several times. But it is not so useful when it is used only once like <name> or <email>.

As I described above, "Your Name" will have less confusion than "<name>" or <name>.

@methane:

I don't think it causes real confusion. Variables are useful when the same word is used several times. But it is not so useful when it is used only once like <name> or <email>.

Okay, I see. As an example, do you think it's useful in the following context for <username>? (taken from an existing section in gitbootcamp):

git clone [email protected]:<username>/cpython.git

As I described above, "Your Name" will have less confusion than "<name>" or <name>.

I agree, I just thought that the italics might be useful, such as "Your Name". It helps to make the text stand out to the reader, and indicate they should substitute their own text there. In the specific case of "Your Name" it's fairly clear either way, it just makes it more obvious.

Okay, I see. As an example, do you think it's useful in the following context for <username>? (taken from an existing section in gitbootcamp):

Yes. <username> is used above (L48):

   git clone [email protected]:<username>/cpython.git

So <your-username> should be replaced with <username> for consistency.
This is the case consistency is important for readers.

It may be more helpful to add more comment like this:

   # Replace <username> with your github user name.
   git clone [email protected]:<username>/cpython.git

@methane Alright, updated, thanks for the review.