search

brackets-userland / brackets-git

brackets-git — git extension for adobe/brackets
Other
657 stars 193 forks source link

Improve README #1333

Open NickVolynkin opened 7 years ago

NickVolynkin commented 7 years ago
NickVolynkin commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

@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.