Munchit1's documentation comments discution
Posted by arthurwolf
|
Munchit1's documentation comments discution October 01, 2017 03:25PM |
Hello.
Munchit1 started a conversation about Smoothie's documentation in this post : link to other reprap forum post but because that post isn't about the documentation, I am moving the conversation here in a new post so things are easier to follow.
If you want to read the conversation up to this point please see the link. For a short recap, he feels that one needs a degree to understand the current Smoothie documentation. That's a complaint I have only ever heard from him, in 5 years of helping hundreds of users a year.
I'll just answer his last message here to get the ball rolling.
For some context on this next one, I asked Munchit1 for specific things he thinks should be improved in the documentation, he answers :
Do you mean this diagram ?
You say there is a problem, but what problem exactly ?
The diagram is accompanied by a lot of text, and both the diagram and the text explain what the user needs to know. What is the problem ?
I want to insist : hundreds of users every month, most of which have no degree or electronic experience, use this documentation ( alone, without any other help ) to get their board to work, all alone. Every month. Hundreds.
So the vast majority of users have no problem with this. You are the only person to complain about this specifically. Or to complain that strongly about the documentation in general. I want to make this clear.
Again : hundreds every month, most of which do not have degree or experience, use this documentation succesfully.
I get very frequent emails from users enthusiastic about how helpful the documentation was to them, and how they find it's very friendly to beginners.
You can search the forums or mailing lists, it's very easy to find examples of this.
In the very beginning of the project, in my enthusiasm I even collected such remarks, until they became so numerous I had to stop to save time. You can find a selection at this link : [docs.google.com]#
It's obvious this isn't the case for you, but what I'm trying to say is : you are an exception here. Maybe english isn't your primary language ( that's my case ) ? Or maybe you didn't pay a lot of attention the first time you read it, and got frustrated enough that you weren't ever able to subsequently read it correctly ?
I searched my inbox and the community forums for this and wasn't able to find it. 3 drivers dying at once is something I'd remember. Did you just contact the community, or did you contact the person who sold the board to you directly ?
We do provide full support, and replace faulty boards, but you have to actually contact us. We can't know you have a problem if you don't tell us.
Why would you need to know what pins are which in the context of drivers dying ? I'm very confused here. Do you have a link to the conversation you are referring to ?
Also, Smoothie is extremely modular : there is no obligation to use a pin for something and another for another pin. You choose what pin you want and use it for what you want ( in most cases ). As such, the documentation doesn't need to specify a lot of things since users can just choose whatever they like and it will work fine.
I'm sorry I didn't understand anything in that line. Maybe it's because I'm not a native english speaker ? Could you rephrase this in a way that's easier to understand ?
There isn't anything called "34F96" anywhere in the Smoothie boards or firmware, I'm very confused what you are trying to say here.
Again, sorry, I didn't understand any of that ...
I'm confused what the complaint is here. You yourself confirm that this is documented.
Smoothie users do not need to do trial and error : everything is documented, everything is explained ( as you yourself just said in this case ).
Again : you are confusing your personal experience with the general case : the vast majority of users do not feel the way you do about the documentation ( and they tell me so. often ). Your feedback is something I have had only maybe one or two other people give me over the past 5 years, with tens of thousands of users.
0.01% isn't the same as "a majority" you are talking about.
I do understand you find the documentation confusing and lacking, but :
1. This isn't what the other users feel
2. You need to tell me specifically what you find is wrong so that I can improve the documentation
I'm very confused here. You agree it's fantastic and it's much better than the other system's documentation. But at the same time it's "not that informative" ?
Again : that's not what the colossal majority of Smoothie users feel. You are definitely in a very small minority here.
I think I can even say with a lot of confidence that you are *factually* wrong about the Smoothie documentation.
I'm not sure why you feel how you feel about the documentation, but it's clear you are mistaken. The best I can do is try to improve the documentation so you are happier about it, but that requires you telling me *precisely* what you find is wrong, and you haven't done that yet. Please help me fix the documentation.
You are acting as if the documentation didn't include wiring instructions, but it does ... Very detailed instructions in fact ...
Also, again please do not give imaginary examples ( there is no such thing as "pin1" or "A4" in Smoothie ), but give real, precise examples, so we can understand the problem better, and maybe fix it.
I have been asking you for problems with the documentation. You say there are many. But when giving an example you *invent* an example ? Please give me a real problem you find in the real documentation ! Then we can discuss it, and if something is wrong, I can fix it.
Please help me understand what is wrong with the documentation by giving me *real* examples of problems, not invented ones like you just did.
If the documentation is so bad, giving me a *real* example should be easy. Please help.
No degree is required. Every month hundreds of users without any degree use the board simply by following the documentation. They do not have to wait 4 years, they do not need a degree, they just need to carefully read the documentation. The fact that the users succeed at such a high rate clearly demonstrate you are wrong on this.
The documentation does not tell the users they are «thick». If you think it does, please point exactly where you think it does, so I can re-word that part to make sure nobody else feels insulted. I am fairly certain this isn't real though ( I wrote most of the documentation ).
You have not given me a single precise example and explanation of something wrong. You say a lot is wrong, you give imaginary examples, but you do not point at precise things you think are wrong.
Please help me by pointing at precise problems ( give me links, give me exact quotations ), so I can find and fix the problems.
Giving imaginary examples isn't helpful, as I do not find they match what is really in the documentation.
Sorry I'm not sure what you mean.
Hundreds of users every month get their boards to work using the documentation. For the few that can't for some reason, the community is in the vast majority of cases able to help. If it can't, I also provide support via email.
All in all, it's incredibly rare for a user to be unable to get the board to work with satisfaction ( I can think of two specific cases in five years, and both were doing very esoteric things ).
There is no reason you can't get it to work like everybody else if you follow instructions, and ask for help instead of giving up.
I strongly recommend you try to get your board working, and if you get stuck on anything, you can email me directly for help, I usually answer within the same day.
Not sure what you mean here too.
I'm sorry I really don't understand what your problem is. I do not think I complained about anything related to the vocabulary/grammar here. Maybe you are ? I'm not sure ... Can you explain better what your complaint is ?
You are certainly free to do whatever you want with your money, but I really think your complaints are not justified.
You are welcome to prove me wrong by providing specific examples. The rate at which users get the board to work without any help is very strong evidence against your case though.
This is what [smoothieware.org] is.
There is a precise technical documentation, and there is, *separate*, the 3D printer guide, which is very precisely a "beginner's set of instructions" to help users get their 3D printers to work, from start to finish.
If you feel this guide doesn't fulfill this role, please give specific examples of what you think is wrong.
I don't understand this request.
A Smoothieboard doesn't have any pololu sockets, why would the documentation include reference to them. This would be very confusing to newcomers.
Also, in setting up a classical 3D printer, users do not need to change pins. so making reference to pin correlation would be information that would have a negative effect on how "beginner friendly" the documentation is.
I don't understand what this means.
You realize that different users have different machines, so we need to explain to users how to adapt configuration to their specific setup, right ? We can't just give instructions that will work for one machine, we need to instruct users how to adapt configuration in a way that will work for them. This means there *will* be some thinking and decision making to do, but we explain in detail how things work and how to make the decision, and how to apply.
If you feel we don't, please point at specific examples.
You seem to be saying this isn't contained in the documentation, but it actually is ...
I want to insist again this is only your feeling, this isn't what all the other users say. The other users do not agree with you there.
I am certain if you tell me this is your experience, then you are telling the truth. But your experience isn't the experience of everybody. The feedback from the users is very clear, both in private and in public.
I do not understand what your complaint here. Can you explain in more detail or maybe point at a specific part of the documentation you are referring to ?
Cheers.
Munchit1 started a conversation about Smoothie's documentation in this post : link to other reprap forum post but because that post isn't about the documentation, I am moving the conversation here in a new post so things are easier to follow.
If you want to read the conversation up to this point please see the link. For a short recap, he feels that one needs a degree to understand the current Smoothie documentation. That's a complaint I have only ever heard from him, in 5 years of helping hundreds of users a year.
I'll just answer his last message here to get the ball rolling.
For some context on this next one, I asked Munchit1 for specific things he thinks should be improved in the documentation, he answers :
Quote
munchit1
the example of an eleectronic diagram (the one with the red lines inbetween the posative wires is one).... just when the non electronic engineer is just getting his/her head around it bammo! bamboozled back to non understanding.(the maual f***ked um up)
Do you mean this diagram ?
You say there is a problem, but what problem exactly ?
The diagram is accompanied by a lot of text, and both the diagram and the text explain what the user needs to know. What is the problem ?
I want to insist : hundreds of users every month, most of which have no degree or electronic experience, use this documentation ( alone, without any other help ) to get their board to work, all alone. Every month. Hundreds.
So the vast majority of users have no problem with this. You are the only person to complain about this specifically. Or to complain that strongly about the documentation in general. I want to make this clear.
Quote
munchit1
the majority of people getting into the 3D printer feild are non starters, theyve live mundain hard worked and long houred jobs to make ends meet, it kills yu brain, so they finaly get enough cash to do something intresting, only to find they needed a degree to understand stuff.(thwarted).
Again : hundreds every month, most of which do not have degree or experience, use this documentation succesfully.
I get very frequent emails from users enthusiastic about how helpful the documentation was to them, and how they find it's very friendly to beginners.
You can search the forums or mailing lists, it's very easy to find examples of this.
In the very beginning of the project, in my enthusiasm I even collected such remarks, until they became so numerous I had to stop to save time. You can find a selection at this link : [docs.google.com]#
It's obvious this isn't the case for you, but what I'm trying to say is : you are an exception here. Maybe english isn't your primary language ( that's my case ) ? Or maybe you didn't pay a lot of attention the first time you read it, and got frustrated enough that you weren't ever able to subsequently read it correctly ?
Quote
munchit1
i have a smoothie board, three drivers stopped at once, i tried as i may to get help but alas
I searched my inbox and the community forums for this and wasn't able to find it. 3 drivers dying at once is something I'd remember. Did you just contact the community, or did you contact the person who sold the board to you directly ?
We do provide full support, and replace faulty boards, but you have to actually contact us. We can't know you have a problem if you don't tell us.
Quote
munchit1
we parted at the 'oh its a lot of trouble' to just tell which board pins went to which driver pins (as the standard noterisations on your board have new names)...
Why would you need to know what pins are which in the context of drivers dying ? I'm very confused here. Do you have a link to the conversation you are referring to ?
Also, Smoothie is extremely modular : there is no obligation to use a pin for something and another for another pin. You choose what pin you want and use it for what you want ( in most cases ). As such, the documentation doesn't need to specify a lot of things since users can just choose whatever they like and it will work fine.
Quote
munchit1
theres one strong indication theres summut up? 'we'll call it fibonderito 73x...do you know what one is? the art of not telling whilste babbling very many important words is the death of an econamy...fact.
I'm sorry I didn't understand anything in that line. Maybe it's because I'm not a native english speaker ? Could you rephrase this in a way that's easier to understand ?
Quote
munchit1
try this one, 34F96 goes to? obviously every one knows what one is?
There isn't anything called "34F96" anywhere in the Smoothie boards or firmware, I'm very confused what you are trying to say here.
Quote
munchit1
call the DIN a ermmm zebady prushous and neglenct to ever explain what one is?
Again, sorry, I didn't understand any of that ...
Quote
munchit1
the axis rename was no problem, it was documented...and yes in reality would have only taken a few minutes to work out by trial and error..alas when you have to 'trial and error' a complete program? 73 other items and sub settings? it means the manual failed.(well it does to everyone else, or more to the point to every one else that it was written for!)
I'm confused what the complaint is here. You yourself confirm that this is documented.
Smoothie users do not need to do trial and error : everything is documented, everything is explained ( as you yourself just said in this case ).
Quote
munchit1
i cant see how you can have the intalect and yet cant understand such a basic concept...the people reading the manual are finding it lacking and quite often confusing....i.e. the majority see fault in it.
Again : you are confusing your personal experience with the general case : the vast majority of users do not feel the way you do about the documentation ( and they tell me so. often ). Your feedback is something I have had only maybe one or two other people give me over the past 5 years, with tens of thousands of users.
0.01% isn't the same as "a majority" you are talking about.
I do understand you find the documentation confusing and lacking, but :
1. This isn't what the other users feel
2. You need to tell me specifically what you find is wrong so that I can improve the documentation
Quote
munchit1
now i actualy thought the web site was fantastik..tbh it was a shed load more info than pritty much all the other guys....thats why i thought it a shame that at the end of all that reading it was quite ermmm... not that informative...from my point of veiw it was a shame that after all that effert ehhhh..yu know...some luvly woffle, thank for trying but..erghhh yu know....???)
I'm very confused here. You agree it's fantastic and it's much better than the other system's documentation. But at the same time it's "not that informative" ?
Again : that's not what the colossal majority of Smoothie users feel. You are definitely in a very small minority here.
I think I can even say with a lot of confidence that you are *factually* wrong about the Smoothie documentation.
I'm not sure why you feel how you feel about the documentation, but it's clear you are mistaken. The best I can do is try to improve the documentation so you are happier about it, but that requires you telling me *precisely* what you find is wrong, and you haven't done that yet. Please help me fix the documentation.
Quote
munchit1
in reality it;s lego building leval stuff......IF you got the instructions... pin 1 goes to A4...woopy do that was hard? etc etc etc..
You are acting as if the documentation didn't include wiring instructions, but it does ... Very detailed instructions in fact ...
Also, again please do not give imaginary examples ( there is no such thing as "pin1" or "A4" in Smoothie ), but give real, precise examples, so we can understand the problem better, and maybe fix it.
Quote
munchit1
now try this, F4 goes via the alternating fubar pin (no pin any where called that is there? no further info?...how can anyone posabley do it? unless you know the board, can build the bord and fully understand all the electronics. (i.e. the manual failed the user).
I have been asking you for problems with the documentation. You say there are many. But when giving an example you *invent* an example ? Please give me a real problem you find in the real documentation ! Then we can discuss it, and if something is wrong, I can fix it.
Please help me understand what is wrong with the documentation by giving me *real* examples of problems, not invented ones like you just did.
If the documentation is so bad, giving me a *real* example should be easy. Please help.
Quote
munchit1
the point is people buy the board from you because they themselves havent got 4 years to do the degree and a further 5 years of exsperience...
No degree is required. Every month hundreds of users without any degree use the board simply by following the documentation. They do not have to wait 4 years, they do not need a degree, they just need to carefully read the documentation. The fact that the users succeed at such a high rate clearly demonstrate you are wrong on this.
Quote
munchit1
.they buy the pre made board in the vain hope the instructions will enable them to 3D print...(it soort of instructs them that they are thick, when in fact it is the manual that failed..i.e. its lego levals of dificulty IF YOU HAVE THE CORRECT INSTRUCTIONS)
The documentation does not tell the users they are «thick». If you think it does, please point exactly where you think it does, so I can re-word that part to make sure nobody else feels insulted. I am fairly certain this isn't real though ( I wrote most of the documentation ).
Quote
munchit1
so after talking round my hat in cuircles over and over again with hints, examples and metofors with exsplanasion you eather cannot or will not understand?
You have not given me a single precise example and explanation of something wrong. You say a lot is wrong, you give imaginary examples, but you do not point at precise things you think are wrong.
Please help me by pointing at precise problems ( give me links, give me exact quotations ), so I can find and fix the problems.
Giving imaginary examples isn't helpful, as I do not find they match what is really in the documentation.
Quote
munchit1
ahhh yes talking me..very clever.
Sorry I'm not sure what you mean.
Quote
munchit1
i threw the smoothie board up on the shelf and marked it down to 'waisted 160 quid'...for good reason....
Hundreds of users every month get their boards to work using the documentation. For the few that can't for some reason, the community is in the vast majority of cases able to help. If it can't, I also provide support via email.
All in all, it's incredibly rare for a user to be unable to get the board to work with satisfaction ( I can think of two specific cases in five years, and both were doing very esoteric things ).
There is no reason you can't get it to work like everybody else if you follow instructions, and ask for help instead of giving up.
I strongly recommend you try to get your board working, and if you get stuck on anything, you can email me directly for help, I usually answer within the same day.
Quote
munchit1
you obviously dont need the money.
methodicaly this becomes aparent...over and over again.
Not sure what you mean here too.
Quote
munchit1
posative feedback, tecnicaly is NOT feedback that is posative! posative feed back in its simplest form is actualy getting 'accurate' feed back.
negative feed back is literally getting no feed back of inacurate feedback.
then we get to misconstrude 'accurate'... because after all the witty intelectual battle is far more important than anything factual....a bit like old women in the battle of the tongue.
I'm sorry I really don't understand what your problem is. I do not think I complained about anything related to the vocabulary/grammar here. Maybe you are ? I'm not sure ... Can you explain better what your complaint is ?
Quote
munchit1
you got the money.. but you'll get no more.
cleva hu?
You are certainly free to do whatever you want with your money, but I really think your complaints are not justified.
You are welcome to prove me wrong by providing specific examples. The rate at which users get the board to work without any help is very strong evidence against your case though.
Quote
munchit1
how about just adding a 'begginers' set of instructions?
This is what [smoothieware.org] is.
There is a precise technical documentation, and there is, *separate*, the 3D printer guide, which is very precisely a "beginner's set of instructions" to help users get their 3D printers to work, from start to finish.
If you feel this guide doesn't fulfill this role, please give specific examples of what you think is wrong.
Quote
munchit1
this pin coralates to polulu pin ''whatever''
I don't understand this request.
A Smoothieboard doesn't have any pololu sockets, why would the documentation include reference to them. This would be very confusing to newcomers.
Also, in setting up a classical 3D printer, users do not need to change pins. so making reference to pin correlation would be information that would have a negative effect on how "beginner friendly" the documentation is.
Quote
munchit1
when enabled with this command ''pin hi'' placed into 'this section' with or without * or dash etc.
I don't understand what this means.
You realize that different users have different machines, so we need to explain to users how to adapt configuration to their specific setup, right ? We can't just give instructions that will work for one machine, we need to instruct users how to adapt configuration in a way that will work for them. This means there *will* be some thinking and decision making to do, but we explain in detail how things work and how to make the decision, and how to apply.
If you feel we don't, please point at specific examples.
Quote
munchit1
actual instructions dummified....with the actual answer and where to put it? the rest is purely an intresting to read.
You seem to be saying this isn't contained in the documentation, but it actually is ...
Quote
munchit1
reason why.....the majoruty of users are people with no clue as to how, they see the web site (i say again it is a shedd load better than the other corps companies....apretiated) and the dream is alive! only neh, they waisted every penny and got a reminder akin to a wet fish slapped in their face...(a metafor for feeling ripped off and mortaly reminded).
I want to insist again this is only your feeling, this isn't what all the other users say. The other users do not agree with you there.
I am certain if you tell me this is your experience, then you are telling the truth. But your experience isn't the experience of everybody. The feedback from the users is very clear, both in private and in public.
Quote
munchit1
i actualy liked quadradics at school, i 'just saw them' they were fun...through uni they were everywhere in all sorts of disguises....matrices were boring, easy but boring... plugging a pin in to a number..yeh boring but whats worse is when the other end is not and will not be defined...it p****ses yu right off.
I do not understand what your complaint here. Can you explain in more detail or maybe point at a specific part of the documentation you are referring to ?
Cheers.
Sorry, only registered users may post in this forum.