Learning to write in a real constructive way

Community General Discussion
1

Hello everybody,

this thread is meant as a real honest attempt to learn.
I hope that everybody who reads this can see this positive intention.
The thread will contain words and sentences that are meant as discussable examples that can be seen as negative examples how to not write it.
These examples are meant to learn from them how to make it better.

So I honestly hope that you can see this positive intention.

A year ago I had a very netagitve experience with a moderator that resulted in a 4week ban. This is history and not object of this thread. The lines above are just to make sure to see the positive intention to learn how to do it right and in a way that will be accepted.

So what is the real subject?
The blink without delay-example that is part of a standard arduino-IDE installation.

I have written a tutorial that takes a different way trying to explain how "blink without delay = non-blocking timing works.

Recently a moderator requested me to stop tutorial bashing in combination with writing "Constructive criticism is always welcome"
To minimize critics I will not qoute the bashing words. I can agree with the moderator that it was not constructive. So I changed the text to this
.
.
Quoting the modififed text:
OK I changed the text to a detailed analyses what it does

In my opinion this classic blink without delay example makes it unnescessary hard to understand the basic concept for the following reasons:

  • the most important reason is that the "classic" blink-without-delay code does not emphasize on the difference delay() is a simple function-call and BWD requires multiple lines of code and works completely different.
    As long as newcomers try to see a delay()-thing in the code they must fail.
  • The classic BWD-example uses three variables
  • the variable-names are not really intuitive and self-explaining
  • variables that are used must be placed in different lines of code
    .

The moderator answered again that this way is still a not acceptable way of writing it.

I am very surprised that this type of writing is unacceptable. Well, maybe I actually haven't learned to write in an acceptable way. If so, I'm very interested in learning how to do that.
Therefore, I ask for suggestions on how to formulate it so that it can be very well accepted.

Now I'm very curious on different ways how the same basic message can be written in a real constructive way that is acceptable.

best regards Stefan

3

@StefanL38 I would be interested in your views on the approach taken in Using millis() for timing. A beginners guide,

4

Hi @UKHeliBob,

The main question of this thread is about how to write critic in a constructive and acceptable way. Which means I see your question as off topic.
As a compromise between no reaction and drifting the thread to a different subject. My answer is in this clickable folded section

click to open

I haven't read the whole tutorial. From as far as I have read it my comments.

In this tutorial you take time to explain important basics.
There are mutliple contradictionary aims in each tutorial:

  • easyness of understanding
  • going into depth to explain details,
  • entry-level of the explanations how much is expected as already learned knowledge
  • using analogies or not

The more the tutorial expects as already learned knowledge the less easy to understand for real newcomers.
The more details the more explanations the longer it takes until a working example is explained

You are building up compleextity over mutliple examples which introduce more concepts like put code into functions etc.

But what is my view about your tutorial?
Has a lot of information = opportunity to learn a lot
adressed towards people that are patient readers and patient learners

WHat do you think about adding pictures that visualise the differences between a dleay() based code and a non-blocking timing-code?

best regards Stefan

5

Which is why I asked you for your views of it so that I could see what you considered was constructive and acceptable criticism

6

Constructive criticism implies giving specific actionable suggestions for improvement.

The following statements could be improved by explaining why there is a problem and what an alternative would look like.

Phrasing perceived shortcomings in a more positive way can also help you get the message across.

For example, instead of the following statement,

you could say:

Furthermore, I would suggest to avoid using bold text or all caps. Italics is usually enough for emphasis.

7

I think if you write in such a way that does not attack or sound condescending or sarcastic you should be good to go. I would have to see what you wrote that got the moderators attention. At least then we would have a concrete example.

It can get a little tricky because some people come off as rude and do not mean it that way. Cultural and social backgrounds can differ so something that might sound ok to me could be insulting to someone else.

I have seen a lot of people give short, smart a** answers though. I have learned not retaliate in kind because I have also been sent to time out. For sure, in the past it this forum was like the wild, wild west. Much better now.

1 Like
8

It seems to me that the more the inhabitants of the forum are concerned about not offending newcomers instead of worrying about how to teach them, the lower the level of the forum.
Therefore, I am for the wild west style with quick and short a** answers, instead of chewing every word, for example as the topic starter suggests

9

This is the best forum whether you like the wild, wild west version or chew on every word version, hands down.

12

My problems with the IDE BWD Example are about using signed ints with unsigned longs in mixed-math. Bad habit!

Time variables should all be unsigned.

13

the Chinese have a concept known as Supreme Excellence. Supreme excellence is not perfection. it is getting as close to perfection as a flawed human being can get

one of the highest compliments you can give a teacher comes from people who demonstrate Dunning Kruger effect. Dimwits who believe they are geniuses. They will tell the instructor "you just put together a bunch of common sense statements"

in reality that instructor thought of everything the student needs to know, sorted them into an order where everything is explained, and presented it to the student in commonly understood language. if the instructor has prepared the lesson properly, a guy who started programming on an Apple IIe and a guy who started coding yesterday will get equal value from the lesson, because everything they need to know is presented in an order that makes perfect sense. if nobody asks any questions you covered every base in an order that everyone understood.

if you think that is easy you have not tried.

2 Likes
14

and if you don't practice, you lose the lesson in long term.

IMO a good teacher might hear "what can I do with this?" before trotting out exhaustive everything examples or maybe just the good short simple ones on following days.
Memory takes time. Too much too fast is "to fail" and some subjects are a lot for a single showing. Give it time.

1 Like
15

Writing constructively requires being able to successfully communicate your thoughts, ideas, and arguments as well as being receptive to feedback and helpful criticism. Here are some suggestions to make you a better writer:

Recognize Your Audience: Take into account who you are writing to. Consider your audience's needs and expectations when developing your writing style, tone, and material.

Organize and plan your content before you begin writing. To make sure that your ideas flow logically from one point to the next, create an outline or structure for your essay.

16

. . . and if there is anything else you need to know to further your writing skills, please feel free to ask.

2 Likes
17

This topic was automatically closed 180 days after the last reply. New replies are no longer allowed.