I dislike tedious, rambling, long-winded instructional texts

I do not like tedious, rambling, long-winded instructional texts. When instructional texts are long-winded they become tedious. Instructional texts should be succinct. The only words that occur should be deliberate and focused. This may seem strange to say, but they should be like Chinese. Every word is concise and deliberate.

For example:

/* To add a click event to an element with an ID of menu, you’d write this: */
$(‘#menu’).click(someFunction);

This is what goes in my notes:

/* add click event to element with ID=menu */
$(‘#menu’).click(someFunction);

Look at how much shorter my version is. You can parse this text very quickly and get its meaning. If you parse the above example you can’t ascertain the meaning easily without having to tediously go through the whole, laborious sentence.

And my terse version is focused and also very clear. Someone who only knows very basic English could understand and grasp what I wrote. If it were run through a language translator it would come out much better – maybe with 100% accuracy, as opposed to the long-winded example.

Language simplicity is actually a thing now: I’ve read that colleges are relaxing English to some extent because there are a lot of international students. For example Asians might not use prepositions because 1. they aren’t necessary to convey a meaning and 2. they don’t exist in most (any?) Asian languages. I don’t see anything wrong with leaving prepositions out and with other things like simplifying tenses. You can say things in present tense only and for the most part the meaning is totally clear.

Look at what I did – I got rid of unnecessary words:

You don’t need to say “to add”. You just say “add”. Add is what you’re doing. Get to the point.

You don’t need articles for the most part. You don’t need “to an element”. “to element” is perfectly clear and actually to me is preferable for technical notes.

Same goes “with an ID”. “with ID” is clearer. It’s better.

And instead of “ID of menu”, for computer technical notes “ID=menu” is actually totally precise, unabiguous, and accurate. In actual code the ID would be assigned with an = operator, so why not use it in the notes also? It means exactly the same thing!

Finally, I completely ditch “you’d write this”. That language almost sounds like some hick wrote it. I understand that the text is trying to be explanatory, but my point is you can sometimes be more effective at being explanatory by making text more succinct, focused, and easy to parse. People read the text and know that what follows is an example. Are you going to put “you’d write this” before every single example then?

I’m taking another course and the entire course lecture materials consist almost entirely of… slides! Concise bullet-points galore! Totally succinct, focused, and to the point. Where it is beneficial, graphics are included, often to help visualize the structure of an entity (such as an IP packet) being discussed, but often also to provide more detailed info (like the names and locations of all the fields in an IP packet).

It’s funny how courses can be so different. I’ve read many technical books that felt too tedious to me to read. Perhaps it’s how my brain works, but I just want the salient points, focused and concise, without long-winded explanations, prefacing statements, appending statements, disclaimers, etc. Just cut to the chase. Make text easy to parse. Highlight what the main topic area is so you can hone in on it fast. Emphasize sub-areas to make them easy to locate. Then list the points clearly and succinctly.

I think another part of the problem is when the author assumes that the reader has a significant lack of knowledge, then they get all caught up in trying to detail everything ad nauseum. To solve that, I think it’s important to establish what prerequisites are required to understand a particular text, and then stick to it. Don’t try to write a text about some technical area that presupposes knowledge of other areas, and then, in the middle of it, try to throw in explanations about those required topics while trying to explain the main topic. This is a sure way to kill the mental flow of a text and bog it down to the point that it becomes almost impossible to maintain interest.