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.

Computer manufacturers and computer accessory manufacturers really need to use consistent terminology.

Frustrated woman. From pxfuel.com.

Computer manufacturers and computer accessory manufacturers really need to use consistent terminology. Their failure to do so makes things unnecessarily difficult.

I am considering buying a computer from Dell since one of my main computers does not support Windows 11. According to Dell the computer has the following display ports: 1x HDMI 2.0b, 1x DisplayPort 1.4, 1x Dual Link DVI.

The problem is that I need to be able to use this computer with an existing KVM that uses VGA. Therefore I will need to use adapters. The question is what adapters do I need.

Computer accessory manufacturers do not use the Dual Link DVI terminology at all. They use DVI-D and DVI-I. In order to determine what adapter to get I had to go to the Different types of monitor ports page and compare the pictures on Dell.com with the pictures on the Different types of monitor ports page to determine that Dual Link DVI is apparently the same as DVI-D. Therefore the Active DVI-D to VGA Adapter should allow me to connect a VGA monitor cable to the Dual Link DVI port.

Computer accessory manufactures do use the term HDMI. The problem is that not one of the search results for HDMI 2.0b to VGA adapter say anything about the HDMI version. They are HDMI to VGA adapters. No version number information is provided at all. I have to hope that the Gold-Plated HDMI to VGA Adapter will do the job.

Thanks to the use of inconsistent terminology buying this computer has been an arduous and very unpleasant experience.

Thank you very much!

Featured

Advice on how to organize an article

The article What causes the ‘Your Hardware Settings Have Changed’ issue on Windows 10? is very poorly organized.

In the introduction the article explains two possible causes of the issue. This introduction is well written and provides useful, and relevant, information.

After the introduction is a Note heading. The first paragraph in this section begins as follows: “If the given solutions don’t work for you, you will have to stop Windows from updating your device drivers”.

At this point many readers will begin screaming at you in rage because you have not said a single word about how to solve the problem, you just explained what is causing the problem.

Next comes several paragraphs that explain how to “stop Windows from updating your device drivers”.

This Note section ends with the ominous warning: here be dragons. The problem is that the impatient reader who is desperately trying to get their laptop working again may never even get this far because they may have followed the instructions on how to “stop Windows from updating your device drivers” and seeing that the issue has gone away closed the web page.

It is only if you continue scrolling down the page past the ominous warning that you find the solutions. Of course some readers will never see the solution because they stopped reading after following the instructions to “stop Windows from updating your device drivers”.

This article should have been organized as follows.

  1. Causes
  2. Solutions
  3. If the given solutions don’t work for you…

The way the article is presented just pisses the reader off. It may also cause them to try the alternative without ever being aware that the article actually does suggest solutions.

Don’t be like Kevin. Please use a logical order for your articles.

My response to a recent tweet by @realDonaldTrump.

Today @realDonaldTrump tweeted the following.

Donald J. Trump
@realDonaldTrump
At 10:00 P.M. on Election Evening, we were at 97% win with the so-called “bookies”.

This tweet has 146.8K Likes.

The problem is that this was in fact expected and is not evidence of fraud or proof that the election results are invalid for the following reasons which I will explain in the simplest way possible.

  1. There is a currently a deadly worldwide pandemic.
  2. Voting in person during a pandemic is a health risk.
  3. Many states responded to the pandemic by encouraging Vote by Mail.
  4. In many states the law required that counting of vote by mail ballots not begin until after the election.
  5. You told your supporters that vote by mail is prone to fraud despite having no proof. Thus many of your supporters chose to vote in person despite the pandemic related health risk.
  6. Democrats encouraged to stay healthy and vote by mail. Thus many democrats did the sane thing and chose to Vote by Mail.

Thus the inevitable result is that at the end of the day the election results appeared to favor Donald Trump because the legal vote by mail ballots had not been counted yet.

Even Attorney General William Barr, a well known supporter of Donald Trump, has said that “to date, we have not seen fraud on a scale that could have effected a different outcome in the election.”

How to make it difficult to find online test results.

Many doctor’s offices have moved access to medical records online. For example, my doctor’s office emailed me today to tell me that my COVID-19 test results are available and I should go online to view them.

I need to know for certain what the results are because I have a surgery scheduled for next Monday that I would have to cancel if I have COVID-19. Whoever designed the website seems determined to make it as difficult as possible to obtain test results.

The page is designed so that on the left side of the page there are the following tabs.

  • Patient Account
  • Patient Appointments
  • Documents
  • Review Medical Record
  • Message a Provider
  • Contact Us

So far, so good. The obvious place to search for test results is the Review Medical Record tab and if it is not there, the Documents tab.

So, I clicked on the Review Medical Record and I see it is divided into the following child tabs.

  • Patient Summary
  • Allergies
  • Immunizations
  • Medical History
  • Medications
  • Orders
  • Problem List

Nothing in that list gives any indication where to find Results.

So, I clicked on the Documents tab. It has one child tab, the Community Resources tab.

Again, no indication where to find Results.

I finally found the Results after I started clicking on every single tab and child tab; there were over 50.

The Results were located in the Orders child tab of the Review Medical Record tab.

If the Orders child tab was named Results I could have found that I do not have COVID-19 in 30 seconds. As it is, it took me 30 minutes!