Pages: [1]   Go Down
Author Topic: The Ardunino documentation quality is very bad...  (Read 1009 times)
0 Members and 1 Guest are viewing this topic.
Germany
Offline Offline
Newbie
*
Karma: 0
Posts: 4
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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
« Last Edit: April 06, 2013, 11:31:15 am by powtac » Logged


Phoenix, Arizona USA
Offline Offline
Faraday Member
**
Karma: 40
Posts: 5581
Where's the beer?
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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...
Logged

I will not respond to Arduino help PM's from random forum users; if you have such a question, start a new topic thread.

Offline Offline
God Member
*****
Karma: 3
Posts: 716
a, b = b, a+b
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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
« Last Edit: April 06, 2013, 01:33:39 pm by fkeel » Logged


Global Moderator
Dallas
Offline Offline
Shannon Member
*****
Karma: 208
Posts: 12939
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset


It looks like you registered just for the purpose of puking that link all over the forum.  @powtac, please stop.
« Last Edit: April 06, 2013, 02:34:05 pm by Coding Badly » Logged

Germany
Offline Offline
Newbie
*
Karma: 0
Posts: 4
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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!
« Last Edit: April 06, 2013, 02:58:48 pm by powtac » Logged


Offline Offline
God Member
*****
Karma: 3
Posts: 716
a, b = b, a+b
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

you do realize you are comparing an electronics prototyping platform with a (web)programming language.
« Last Edit: April 07, 2013, 05:36:52 am by fkeel » Logged


Pages: [1]   Go Up
Jump to: