Advice on writing a clear and correct technical article.

Woman screaming in rage,

Please, if you are writing an article like Git Fixes: The Current Branch Has No Upstream Branch in which you attempt to explain how to solve the “fatal: The current branch has no upstream branch” error, do not use the wrong branch name in your sample commands.

For example, do not claim that the problem can be solved with the following command.

git push -u origin master

This error cannot in any way be solved by the above command. Why? Because as you correctly point out in the beginning of your article, the reader is not working in the master branch. The only reason the reader saw the error in the first place and did a Google search to find your article is they created a local branch that is most definitely not named master and an error occurred when they attempted to push the changes. The above command is only valid if they are working in the master branch.

The moment the reader sees master in the above command when they know for a fact that it is not correct the begin to question you credibility.

You started off so well in the third paragraph when you included the following.

git push --set-upstream origin <branchname>

In the above example <branchname> makes it clear that the reader is supposed to insert the name of their own branch in that location in the command.

You started off so well. But then you messed up by putting master where you should have put <branchname> throughout the rest of the article. The moment a reader sees master where they know for a fact that it does not belong, your poor reader may go to another less detailed source rather than figure out what you meant to say. I had to read ten other less well written articles before I figured out what you meant to say.

Reading your article could have been a pleasurable experience causing me to be thankful that the solution was so easily found and implemented. Instead it became an hour long headache.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.