Weāre engineers. Documentation is not generally a priority
However, when one is trying to sell a product, documentation can be a pretty big selling point. Microsoft isnāt selling NETMF, though, so I wouldnāt look to them. If a new rededicated effort from them means nothing but VS2013 support, I would guess that revamped documentation isnāt a priority for them.
Reading documentation is unnatural. Remember Joel Spolsky? The big three points are:
People canāt read.
People canāt control the mouse.
People canāt remember.
So, updated documentation will only work partially. Gadgeteer is about [em]coding[/em], not [em]reading[/em] anything. Thatās, actually, a general principle. Manuals are for lamers only. The only reason somebody [em]might [/em]start reading something, is because something is not working. And if we want Gadgeteer to fly off, it [em]must work out of the box[/em].
Thereās a huge (and quite messy) documentation section, but where are the example projects and solutions, that may be dowloaded and run on any board, any framework, any time, with no conditions?..
I have invested maybe us$2,000 in gadgeteer components, but keep ending up back with other platforms like arduino pure and simply because gadgeteer is too frustrating. I do agree documentation is a last resort, but the examples and solutions do not work without know how. Iām currently trying again with a cobra board, but pick up an example and you have to complete the solution if you know how to get the example to work. I will also add some documentation is necessary if it exists itās scatter all over this site so you have to search in Several places to join the dots!
I hope GHI and Microsoft learn from this thread if they are serious about getting the wider community to use gadgeteer!
We could spend a couple weeks just discussing all the pro.s, con.s, where, when, how, what, and why of the current organization of the docs and the website!!
There are two things that are obvious (1) there is a tremendous amount of good (!) documentation in codeshare, the forum, codeplex, and our own materials. Sorting through that,and providing simple/easy navigation, is a monumental task. (2) The diversity of the audience ā programming, hardware, development environment ā is also vast, making it difficult to cover the material in a way that satisfies everybody.
That said, when we find something doesnāt work, we try something else!!
We prioritize our efforts based on customer needs; not our own desire to make a better documentation widget.
We are ever so lucky to to be part of such a great community that solves problems, discusses issues, suggest improvements, and just has funā¦ ( :dance: )
Donāt spend weeks discussing and sorting, place example solutions specific to each development board so they can be downloaded, compiled, deployed, so that they work with no messing around and then people like me can use the debugger to step learn, hack and have fun ā¦ Now whilst I want to have fun, Iām also trying to develop a serious product too!
I must say, I think there is BIG MONEY in this arena, if it was easier to grasp.
I know a 17 year kid that got the Cerberus Tinker Kit last Christmas, he has read the getting started book front to back, and spent much more time than his mother think is reasonable. And asking him about how he liked it, he said: āI would like to have some code running on my boardā¦ā.
He is never going to be a GHI customer - and will probably soon buy a stupid Arduino clone from Kickstarter.
But he will have a few simple lines of blinky WORKING example.
Just my two centsā¦ but it would be useful to do something like mikroEledtronika does on each of their product pages. They have a link to a zip file with examples for that product.
How does that saying goā¦ āan example is worth a thousand wordsā.
As on MSDN there is a dropdown with version on it, so you can choose what document version you want. It has previously been suggested to adopt that in document section, at least for all developer resources with examples.
The main point about age and complexity it very true and can be summed up as the innovators dilemma. You need to keep adding new functions and features to keep existing customers happy. In the meantime some company comes along and offers something cheaper , less functional and simpler and start stealing market share. This is the great disruptive techonology problem that very few companies escape. Think Msoft windows vs iOS and Android. Windows has far more functionality than either , but still finds its loosing ground to āinferiorā competetion.
Iām not sure it applies to NETMF currently though. I have never tried Arduino, but the last embedded chip I tried was a dsPIC. For this comparison NETMF was way easier. I had a full ring binder full of data sheet and documentation for the PIC and eventually had to give up due to lack of time . I knew the chip could do the task, but it took so long and debugging was so poor I had to abandon it.There was a whole array of compilers to choose from, each with subtle differences and no easy method of deciding which to choose. Should I pay more to get compiler x of get the free compiler y? Which has better documentation and support? There were so many descisons and choices to make before even starting and so little information to guide me.
In comparison to this NETMF is childās play. I love it. What bugs me most is when a feature is supposed to work but doesnāt. Or it isnāt immediately obvious that is isnāt supported. The documentation is mostly very good, but occasionaly out of date or not supported on whatever board you are using.
At the end of the day I think GHI are doing an amazing job with the people and resources they have. The 2014 ārefocusā is exactly what they need to be doing right now.
Canāt remember who said that things should be made as simple as possible, but no simpler. We are at, or near that point. Personally I donāt thing gadgeteer (software wise) actually makes things better. Plain MF is simple enough and far more flexible. Having both is confusing.
The problem for me is all the changes to namespaces for each release of the SDK. This makes it very messy and simply choosing a new SDK to build you code does not work.
There needs to be more standardisation in this matter. I know GHI is trying to tidy it all up, but it means a fair bit of work to change over to the new SDK each time if there are so many changes like this.
Take Android development, the same SDK on every release can be used to build your code to run on anything from Gingerbread 2.3 to Kitkat 4.4 without any changes to your code for each update to the SDK. Those items that are deprecated are marked in your code but it will still work if you donāt want to make any changes.
Another thing that this messes up, is the documentation and code samples. Look for instance at the PPP sample that Gus posted in codeshare. It doesnāt work because all of the function names etc are no longer in the latest code. This will be the case for a large number of the codeshare samples.
As Njbuch points out, someone new to NETMF is going to find it frustrating if he uses any code on the site and it doesnāt work.
Let me recap at least one thing which I think is important to respect: VERSIONS
Its important for everybody that the documentation and code samples are clear marked with the firmware its tested for. And likewise its important for GHI and Microsoft internally to have tools that make it freaking easy to maintain all sorts of versions of documentation and core samples.
When you submit a code snippet or project it should be a required field to put in versions of framework as well as board. And be asked to update the code when new versions appear.
