Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve README #1333

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Conversation

NickVolynkin
Copy link

  • replace instructions for SSH with a short introduction
    and a link to a manual by GitHub.
  • Replace bold formatting with headers of appropriate level.
  • Indent a code block to make it belong to a list item.

* replace instructions for SSH with a short introduction
  and a link to a manual by GitHub.
* Replace bold formatting with headers of appropriate level.
* Indent a code block to make it belong to a list item.
@NickVolynkin
Copy link
Author

NickVolynkin commented Apr 13, 2017

Hi, @zaggino!

Here are some quite drastic changes which I'd like to explain.

I strongly advice you to exclude the detailed SSH instruction from README. See, there's a rule with technical writing: in docs for some product you should not document other products. Here both SSH and GitHub are not your products. If you document them, you have to support the docs. For example, the cog button was replaced in the latest GitHub redesign, so the readme became outdated. Would you like to spend time on updating the README with a new button name? Time spent on documenting other products is time not spent on developing your own, so you probably would not.

One more thing about "difficult". I'd not recommend calling things in your product "difficult" because, well, it discourages users from using it. Give an instruction and let the user decide if it is difficult for them.

The code block is just indented a bit more so that it is aligned with the text in the list. For headerst it's much better to use the header syntax (## text) than just bold formatting (**text**). For example, the header syntax makes a linkable header. It's quite common to give a link to a certain part of a long document, like README.

@zaggino
Copy link
Member

zaggino commented Apr 13, 2017

Hi @NickVolynkin , agree with the changes, but could we preserve the currently removed section Working with SSH repositories into the docs folder maybe and point a link to it saying it might be outdated?

I'm not the author of those (even if Git blame says so, I definitely know I haven't written them) and the original author probably had his reasons for putting those together.

While I certainly agree that this repo should not document other products, there are users who are not skilled enough to understand other products documentation easily and these steps might make it easier for them.

@NickVolynkin
Copy link
Author

NickVolynkin commented Apr 17, 2017

@zaggino, hi again.

I agree that just by replacing the instruction with proper links we can make the document less useful – even when the linked documentation is good enough. Then we should probably start with thinking over the structure. Docs folder sounds really good.

Unfortunately, I'm a bit overloaded at the moment and cannot do it right now. Would you prefer to leave the PR as it is for some time or to close it and create an issue in the tracker? I'm fine with both options.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants