Go Down

Topic: The Ardunino documentation quality is very bad... (Read 1 time) previous topic - next topic

powtac

Apr 06, 2013, 03:35 pm Last Edit: Apr 06, 2013, 06:31 pm by powtac Reason: 1
The Arduino documentation quality is very bad:

  • A lot of known bugs (Ethernet!) were not mentioned in the reference

  • Comments in the reference are not possible



And this forum has a poor UX. It is almost impossible to search for two words, since the results come up with pages showing results of only one word... And also searching for "()" for example for searching for code is also not possible.

Hopefully there will be soon a Stack Overflow Community about Arduino: http://area51.stackexchange.com/proposals/49538/arduino?referrer=aGIGu9OJQHvTwCU-axkKUA2

Dear Arduino crew please

  • switch to Stack Overflow. It pushes the quality of the documentation a lot!

  • Also provide general access to edit the references.

  • Please fix the forum search.

  • Please remove those unnecessary forum post forum features. Nobody uses them except for "code"

  • Please find a better style for the code block in forum posts, they are annoying and very big, the dotted lines are not beautiful.

  • Please reduce the layout of the forum it's very noisy.

  • Please remove stupid features like icons from the forum.

  • Reduce the number of forums, it is hard to figure out if a question is technical/software/setup or whatever. Better add a good tagging system. Not this 2003 style of forum categories...



I do like Arduino a lot!

Stack Overflow: http://area51.stackexchange.com/proposals/49538/arduino?referrer=aGIGu9OJQHvTwCU-axkKUA2

cr0sh

First off, I am glad that there will likely be an SO forum for the Arduino - but to somehow say it could or should replace this community is daft in the extreme.

Myself and other long-time members of this community that has grown up here around arduino.cc have gone through and helped each other in immense ways over the years. We even survived the transition to this "new forum" from the old one (and part of me still misses that old one!). You can't just barge in here and demand a bunch of changes; that ain't gunna fly (whoops! sorry, slipped into redneck mode there - heh!)...

The documentation that is here on this site is for the base Arduino only, for the most part; anything extra like ethernet and such is up to the providers of those shields and modules. If you don't like it - do something about it. We aren't here for your beck-and-call; if you want better documentation, set up a blog and write better documentation, then post it here for us to see. You'll provide a valuable service to the community, and gain credit that way. Heck, you could even just post a thread about the better documentation, or post it in the playground, or whatever. Just don't expect to scream and whine about something and get it fixed - participation is key, here.

Now - I agree that search can be a pain - which is why I tend to use google search to search the site (heck, google has most of it indexed anyhow). As far as all the features and such you don't like - some of use them and like them very much, thank you - we like options. Some of us also don't mind a ton of information and "clutter" (you should see some of our workshops that we assemble electronics in - you'd probably have a heart attack).

Also - as far as the number of forums - I actually think (IIRC?) that the number of forums is way better than what we had in the past - in the past, we had too few forums, and so things were jumbled all up everywhere - you had so much intermixing of projects, questions, and such going in the wrong forums and wherever, that it was really hard to follow. You really want to return to that? Hah - you don't even know - you weren't here, then...
I will not respond to Arduino help PM's from random forum users; if you have such a question, start a new topic thread.

fkeel

#2
Apr 06, 2013, 08:26 pm Last Edit: Apr 06, 2013, 08:33 pm by fkeel Reason: 1
documentation:

the Arduino documentation is extremely good. Could you please show me any other platform with a similar amount of resources and documentation?
I think your statement that the documentation is poor might stem from a misunderstanding of what arduino is.

forum:

I agree that there is lots of space for improvements. However, as cr0sh has mentioned - this is a process and jumping in, requesting a clear cut like you are doing is not especially helpful. Also, the number of individual forums is actually something which sort of came about out of experience with the old forums and to somebody who has been around for a while it makes sense. (I mean - comparing it to before when we had less sub forums, this is a much better solution.)

Having said that - I too would welcome a tagging/filtering system. I suggest we continue the discussion on that topic here: http://arduino.cc/forum/index.php/topic,158153.0/topicseen.html

Coding Badly

#3
Apr 06, 2013, 09:29 pm Last Edit: Apr 06, 2013, 09:34 pm by Coding Badly Reason: 1

It looks like you registered just for the purpose of puking that link all over the forum.  @powtac, please stop.

powtac

#4
Apr 06, 2013, 09:51 pm Last Edit: Apr 06, 2013, 09:58 pm by powtac Reason: 1
Thanks for responding and understanding my approach.

I'm very familiar with the PHP documentation. If there is or was any problem about a function, it has been mentioned in the documentation with a big exclamation mark. And every little useful information about a function is on that single function page. If it is not on the official part there, there is still a comment below by a user. Also the "similar" functions section is very useful in the PHP documentation. It leads me to other function which might be more useful for my case.

I miss all these features on the Arduino page. It's a mess. I avoided to register for the forum for years...

When it is a known problem that a SD card has better to be removed when working with the Ethernet Shield it should be on every single page of the Ethernet reference! Why not?.

For a valid HTTP request which does not produce an error by an Apache server you need four lines of commands not only one. Only a one liner looks nice in the documentation but does not work on most real live situation. A notice would be very, very helpful.

There are undocumented functions which come up in forum example code but they are not documented. For example "Ethernet.status()".

All those problems took me hours and days to solve. I'm sure with a better documentation it would have taken only minutes!

Thank you very much for responding.

I was about to remove the link to the SO page, but somebody was faster. Sorry!

fkeel

#5
Apr 07, 2013, 02:53 am Last Edit: Apr 07, 2013, 12:36 pm by fkeel Reason: 1
you do realize you are comparing an electronics prototyping platform with a (web)programming language.

Go Up