The Git syntax is ambiguous and vague. The documentation typically describes commands that could have multiple meanings in equally confusing terms.
For example, the Git Cheat Sheet definition for the git "rebase" command is "apply any commits of current branch ahead of specified one". Is this clear? Does everyone understand what the "rebase" command actually does?
Tools such as Git should use syntax that clearly describes the direction and results of the command. Modern documentation should strive to follow standards such as the Simplified Technical English standard. The goal of Simplified Technical English is clarity. One of the key rules of Simplified Technical English is to write so that the message cannot be interpreted in multiple ways.
The syntax of a development tool should also follow the goals of Simplified Technical English.
Git syntax and documentation are the poster-children for ambiguity.
Git takes a substantial learning curve. Very few developers pick it up in a day. The underlying concepts are straight-forward. Imagine the pain, suffering, and costs that could be eliminated if Git syntax and documentation were developed with clarity in mind.
I have used Git for a year. Today, I lost six hours trying to figure out the best way to remove files from a pull-request.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
The Git syntax is ambiguous and vague. The documentation typically describes commands that could have multiple meanings in equally confusing terms.
For example, the Git Cheat Sheet definition for the git "rebase" command is "apply any commits of current branch ahead of specified one". Is this clear? Does everyone understand what the "rebase" command actually does?
Tools such as Git should use syntax that clearly describes the direction and results of the command. Modern documentation should strive to follow standards such as the Simplified Technical English standard. The goal of Simplified Technical English is clarity. One of the key rules of Simplified Technical English is to write so that the message cannot be interpreted in multiple ways.
The syntax of a development tool should also follow the goals of Simplified Technical English.
Git syntax and documentation are the poster-children for ambiguity.
Git takes a substantial learning curve. Very few developers pick it up in a day. The underlying concepts are straight-forward. Imagine the pain, suffering, and costs that could be eliminated if Git syntax and documentation were developed with clarity in mind.
I have used Git for a year. Today, I lost six hours trying to figure out the best way to remove files from a pull-request.