Welcome! Log In Create A New Profile

Advanced

Munchit1's documentation comments discution

Posted by arthurwolf 
Munchit1's documentation comments discution
October 01, 2017 12: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 :

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.
Re: Munchit1's documentation comments discution
October 01, 2017 02:20PM
dood, i stated not specificaly at you

i also stated the web site is far better than any others

i also stated i metaforised and exsplaines why over and over

the whole point was why cant there be a concise simplistic manual....like an idiots guide.
reason.. a lot of folks are not up to reading all of those pages and cross referencing.....

regaurding your not understanding what i said?....................ffffffffffffffffffffffffffff overly exsplained my self surely?? with detailed readon, cause and effect, and alas all you made of it was petty nit picking which only leads to a longgggggggggg slanging match and a battle of empty words..
conclution...once again can only be you aint getting any more of my money. its a conclusion many will make...and many more will buy anything else that will run your software.
i've given the why they will buy something else.. again its posative feed back...that 'you cannot understand..'
as it stood when i bought the smoothie, and how much info there was on the web site yours was THE ONE TO BUY...the websites been vamped and yes it is better again, alas...how can buy any thing from you hen you wouldnt exsplain a simple pin to pin proceedure? come to that i hink the board was only 8 months old (with a 2 month non use)..aghain, that is just my personal complaint about it.

the rest is a request for a simplyfied manual that the majority can follow and get the printer running....again, one you cant understand? why cant you understand that?
electronic abreviasions are subject to many differing aparels... i was used to 5, yes 5 diferent abreviation systems....duh... without knowing which? how can you know?(and not that particular dioagram above...again it wasnt the point in whole...the point brought up was why arnt 'manuals' in general understandable with most of the manufacturers...not aimed at you in particular!





my personal complain relates to near on 12 month ago when i could not get help on the forum, eventualy you did email me and sort a couple of issues out (that were not curently on the web site at the time) but, when the 3 stepper drivers packed in at once there was no offer to fix, payed or non payed, when i asked how to use the break out pins your reply pritty much said its too much hasle and you didnt tell me how, i only needed the pin translasion so i could plug in the external stepper driver?
as such the board was thrown and i actualy 'just gave up and went away'..........i could only conclude you'd got my money now i can just go away.. pritty much like greeetek or many of the companies.
Re: Munchit1's documentation comments discution
October 01, 2017 02:29PM
Ok, I'm really sorry, I don't usually do this, but I think I'm giving up ...

I don't understand most of what you say, and what I understand seems extremely illogical and unreasonable.

You are very welcome to your opinion and spending your money however you want.

I would really like for you to point out something *precise* in the documentation that is wrong.

Also, you complain about some things, like "the pin to pin thing", but do not explain what that is about precisely enough for me to understand. Can you please explain in more detail what the story is with "pin to pin" ?

On the overall subject of the documentation not being good enough without a degree, I'm sorry but that's just unreasonable, and the hundreds of users using the documentation every month clearly prove you wrong, so I just won't be expanding on that anymore.

Again : if you have something *precise* to point out that is a problem in the documentation, I will be very glad to fix it.

Cheers.
Re: Munchit1's documentation comments discution
October 01, 2017 04:52PM
the exsiting documentation is ok for exsperienced users...

the request was for a much simpler quick guide beginners can just read through in one go..


and apology excepted..

i got my hopes up with the board..so maybe some of my fault is there.
Re: Munchit1's documentation comments discution
October 18, 2017 11:17PM
I get what he's asking, and I'd have to agree.
A lot of the documentation is perfectly coherent to a software/hardware engineer, but to a lay-person who's trying hard to pick up new concepts, it's often not helpful.

Example: I asked on the Google group where one would connect the second wire on a momentary switch to activate a module.
Answer: "usually it goes to ground, but it can go to either, depends on if you want it to go high on close or low"
That's likely an exact and concise answer (and I am thankful for the fast reply), but not necessarily helpful to a QC in an aluminum foundry.
After thinking about the reply, I understood what he said, but not the reason one would want to go high or low, so that switch sits in it's box, and my board remains wired as it was.

I'm sure the board and software are capable of some really cool things, but It cost me a car payment, and I'm not throwing wires on it without knowing and understanding what I'm doing. Perhaps more common language is needed to be used in general across the whole documentation, because I find myself Googling for explanations and examples of what the documentation is saying, when the answer should be right there.
Re: Munchit1's documentation comments discution
October 19, 2017 01:45AM
But but ... there's a page just for that, that goes over the details : [smoothieware.org]
Re: Munchit1's documentation comments discution
October 20, 2017 01:01AM
Yeah,
Thanks.
Re: Munchit1's documentation comments discution
November 04, 2017 02:28PM
Maybe an 'Idiots guide to Smoothieboard' is what some folks are looking for. A nice well defined example of how to set up the hardware and a matching config file to go with it. Smoothie is wonderfully configurable from my point of view (I'm an EE so its all pretty easy for me), but I guess there are plenty of people for whom having options just leads to confusion, as its not always obvious what the consequences of their choices will be.
Re: Munchit1's documentation comments discution
November 04, 2017 03:11PM
Quote
twospoons
Maybe an 'Idiots guide to Smoothieboard' is what some folks are looking for.

This is *exactly* what [smoothieware.org] is supposed to be. "Idiot's guide" was even the name of the draft ...

Quote
twospoons
A nice well defined example of how to set up the hardware and a matching config file to go with it.

This works in the universe where everybody has the same 3D printer, and doesn't in our world ... we removed *a lot* of possibilities from that file to make it easier to digest. If we removed more we've essentially make it useless to large parts of the user base ...

Quote
twospoons
Smoothie is wonderfully configurable from my point of view (I'm an EE so its all pretty easy for me), but I guess there are plenty of people for whom having options just leads to confusion, as its not always obvious what the consequences of their choices will be.

I really don't see how we can have less options, but if somebody has ideas I'm very eager to hear them.
Re: Munchit1's documentation comments discution
November 04, 2017 09:10PM
I hear everything you are saying, and it all makes sense (and I personally don't think for one second you need less options!). I understand how hard it is to create a guide when there are so many printer variants. Maybe the real answer is "If you don't understand this stuff, go buy an off-the-shelf printer". Is that too harsh? Perhaps one or two example smoothie builds (one cartesian, one delta?) showing exactly how it all hangs together would help those with low tech ability. Rather a lot of work, though. Might be some builds already documented you could link to perhaps?

Personally I found your documentation reasonably easy to follow, but I design and build electronics for a living so its all pretty much a no-brainer for me.
Sorry, only registered users may post in this forum.

Click here to login