Main Site Documentation

General comment RE : code.tinyclr.com: No place for comments, no hardware setup notes


#1

This is a noob comment. Apologies if this is there, or if I missed something.

Good news: The tinyclr world is really amazing. Forums that get quick responses from the vendors, nice code library (code.tinyclr.com)

Bad news: The sample code area is both missing needed info, and lacks the ability for users to give feedback.

Example of the moment: “Library — BLINKM COMMAND WRAPPER” This is totally cool. Just what I was looking for! But I have no idea how to wire up the blinkm to the panda… So I have to “go fish” to figure this out.

Other example of the moment: “HTTP CLIENT SAMPLE CODE FOR FEZ CONNECT” I, and other users on the forum have noted that this sample is flawed (or the underlying implementation is flawed). There is no way for us to comment on the code sample, other than rating it down (which isn’t really the point). No way for us to warn the next guy of the issues we have discovered.

Just imo.

Thanks for the great ecosystem!


#2

This has been brought many times before. I agree this would be very helpful. There is no way to get back in touch with the author of a particular code submission, unless he is a frequent user of the forum.


#3

Sam,

Believe me you’re not the first to bring this up. I personally think everything should just go to the WIKI. The code site is just too limited in features and it only adds to confusion to have multiple places to search. Keep this in mind when you start adding your posts :wink:


#4

@ samjones3 - Glad you find the (my) blinkm wrapper useful. Since I’m assuming you have one or more of these, you probably also have reviewed their documentation and know that these use I2C. The I2C pins on a Panda, for example, are well documented in various places.

Regarding your “bad news” comments - the code site does not serve as a place for fully explained “how to” examples. That is what the wiki is for. As far as feedback on the code goes, you have this forum for that. Also, that code has no licensing attached, so you can do whatever you like with it, including sharing any improvements.

I agree that it might be nice to have all of these sites cross linked in such a way that you could spend less time “fishing”. As an avid fisherman myself, however, what fun would it be if somebody else catches the fish for you?

[edit] - must be the artist formerly known as EricH is a frequent user of the forum :wink:


#5

I2C pins on a Panda

Yes, I know the device is I2C.

Yes, I have made this device work before (an an arduino)

No, I really do not what I am doing (but I fake it)

No, I am 30 mins in, and have no idea (yet) on how to physically do I2C on a panda board.

Bottom line:

– I estimate that I will eventually get this to work.
– But it is a LOT more time and effort than doing it on arduino
---- This eliminates a lot of the benefit of using visual studio
– I do not believe in fishing (sorry). I believe that code in one place, that requires a certain physical setup , should reference at the top, in a comment, either the info needed (wire up your blinkm with pin A to pin 5…) or should have a link to the docs that say how to do it. I believe that partial, incomplete information is a problem in our industry, and that our goal as professionals is to present complete, self documenting solutions that any other professional (or in this case, also amateur) can easily follow and use for quick success.

Thanks a ton for the lib. In another 30-60 mins, I hope to have it working! (took 10 mins total on arduino)


#6

@ Ian and @ ransomhall,

I see several problems with using the Wiki for code submissions from the rank and file:
[ol]Discoverability - The code site has tags, and a more intuitive (IMO) search feature.
Ease of submission - With the Wiki, all formatting is up to the author, and how the code and explanations are organized can and will vary wildly from one author to the next. As a reader, how can you know where to expect to find the relevant code?
Attachments - To provide attachments for the Wiki, an author must (correct me if I’m wrong) link to a file that they host elsewhere. With the code site, you simply upload it.
[/ol]

I think you can definitely make a strong argument for much code-related content on the Wiki. For example, if I was going to write a tutorial (i.e. more text description/discussion, and not mostly code), that would definitely make more sense on the wiki. But when I’m looking to share a quick demo, or a helper library, I think the Code site is ideally suited for that.

I think having fields for the hardware setup would be a nice addition, and a way to comment and/or contact the author, too. Just not sure I agree that “use the Wiki” is the right answer in all circumstances.


#7

Personally I don’t like the Wiki. I prefer the Code site for publishing and searching for code examples. I agree that it would be useful to add a method of contacting the author and to provide feedback for other users; and it would be useful to allow more images and linked files.


#8

I’m not implying the wiki is perfect but I’m of the opinion that all submissions should be detailed enough that someone on the site for their first time can find a code sample and all the information needed to set it up both electronically and software-wise w/o any additional help. You can’t get anywhere close that that with the Code site. Yea, it’s a little more work (you have to use code tags) on the wiki but at least you have everything required to make a quality addition. Ultimately, I would love to see the two sites merge and be tightly integrated with the forums :slight_smile:


#9

Ian,
Yes I agree. Ideally the “code” site would have these features:
[ulist]a link to the author
a description area
a syntax-highlighted source code area
a feedback / discussion area (maybe linked to this forum)
a way to search by description and/or source code keyword
a way to filter search results by tags and/or category / sub-category
the ability to upload multiple images and files[/ulist]


#10

We are, as always, working on improving. We have a long list of improvements for the code section. Your comments here are now added to the list.

Thanks everyone.


#11

Ahem … as I’m gulping down my morning coffee I can’t help but wonder what all the whining is about. Yes, these sites could be better organized, but so could 98% of all web sites! And yes, it may be confusing to the uninitiated, and even sometimes to the old timers before they’ve had their coffee…

While GHI is continually striving to shine the silver platter they hand us this stuff on, I find it shiny enough. A large part of the perceived problem that ANYBODY can submit ANYTHING. It’s up to each of us to use it with objective skepticism. I’ve found the content of both the code and wiki sites to range from barely usable to savant like genius. Authors in the latter category take the time to improve their submissions over time, with or without feedback from the community. The majority of it is “fire and forget”, however. IF you happen to use some of this dubious development without a healthy dose of the aforementioned skepticism, better organization will fix nothing.

Must be extra strong “rant” coffee in my cup today :slight_smile:


#12

@ ransom Pour another cup… :wink: I don’t think there’s any whining going on here just some constructive criticism. We all want this community to be THE best resource for NETMF on the web. So offering up ideas to help improve the quality of the content is absolutely relavent anytime. I’ve been frustrated many times by the code site when I found code that says it does exactly what I want but there being zero instructions on how to setup the electronics side that the code was written to demonstrate. I’m willing to bet that many of the “fire & forget” code samples would include a simple photo or schematic of the electronics setup IF there was a way to include it in the post.


#13

I agree with Ian. I don’t think we meant this as critcism of the web sites or GHI. I think we both really appreciate the effort that GHI has put into all their products including their web sites. I personally am fairly happy with the Code site, but that doesn’t mean it couldn’t use some improvements.


#14

Wow, this thread covered some ground!

I do not mean to whine, whinge, or cry. I have, I think, two choices:

  1. Just “take my lumps” and work through the 100 issues we all work through silently, keeping my experience to myself.

or

  1. Share my observations / thoughts on what I experience.

I can tell you simply: Using Panda and the GHI world has been much more painful for me than using Arduino and Netduino.

In Arduino / Netduino land, there are full examples that apply to my situation, and they work with straight copy and paste. No real thinking required. I got everything I ever tried in arduino / netduino land (ethernet, http get, blinkm driving) working quickly, directly, with no spelunking (er, fishing?) required.

In GHI land, I get it all working, but it easily takes 5x or even 10x the effort. I have to isolate bugs in the ethernet http get (hours and hours). I have to consume blinkm libs that dont show the example "using clause in the usage example, sending me digging for an hour.

I want to do wifi on panda, I gotta hoe my own row.

I am making progress, and the community here is GREAT.

But it ain’t as easy as the other platforms, and the layout of the material is part of why.


#15

I think the one thing that we should take from this discussion is that everyone joins this community with different experiences and expectations of what “samples” are available.

While we’re comparing communities, the Arduino community has been very popular for some time, meaning they have a large contributed source of examples/functions etc; in contrast netmf is relatively new, so there’s a degree of immaturity in code examples. I can’t speak for how the netduino community has formed or grown (as I have no experience there), but to some degree they may be in a better situation as their devices support the standard netmf networking which means the standard examples work; the USBizi line of chips are too small to support this natively so the Wiz5100 chipset was selected as a way to offload responsibility for the networking with low memory overhead (this is the same standard chipset that Arduino has built their networking support around).

My 2c (that’s probably 3c in the US at current exchange rates) is this…

1c: The code site doesn’t really help a new person take an objective picture of how “mature” a code snippet may be. That’s important. Community feedback should be able to be associated with an item once someone has tried the code - but that’s feedback that GHI already have on their radar. Perhaps simply making it clearer to people that the code repository is community sourced and use with a touch of caution would help this; perhaps another measure would be a forum category to get guidance on code from the code box, where someone is free to ask for assistance to understand the code or discuss issues.

1c: A great wealth of “approved”, “simple test” applications would benefit everyone. Think your button or SD card doesn’t work properly in your own example app? Just get the approved test app and if it behaves as documented then the problem isn’t in your hardware, it’s in the way you coded your own app. These could at least show one sensible approach to implementing the chosen “device” but with the power of C# there are a large number of different ways to finally implement these “devices” in your own code.


#16

I love this site, but wouldn’t it be really cool if all the NETMF & Gadgeteer communities rallied at the Microsoft sites/forums the way they do around other Microsoft technologies? I LOVE the new forum design at netmf.com. (except for the fact it doesn’t have code tags…)

“I have a dream…” of a day when I don’t have to do a web search that doesn’t look like “(netduino, fez, netmf) I2C”

Imagine a code site that has an example and tabs to show customized versions of the example for different board types like you often see in MSDN for VB, C#, JavaScript, etc.

I can also imagine the holy [board] wars that would break out in such a community and that’s a shame…


#17

@ Ian

It does make me kind of sad that there’s so little traffic on the netmf gadgeteer discussion site, but I’m not convinced that’s something that can be engineered. IMO, it’s human nature to gather in communities of common interest, and people tend to have strong brand loyalties, so it’s not terribly surprising to me that communities have coalesced around GHI’s forums and around the netduino forums.

I agree that it would be lovely to see one code site to rule them all…perhaps this is an opportunity for someone in the community to step up and host a coding neutral zone. :slight_smile:


#18

Brett nailed it on the head, for me anyways by saying "I think the one thing that we should take from this discussion is that everyone joins this community with different experiences and expectations of what “samples” are available. "

when i first came here, i was so confused my the different code sections i was going nuts. You go to Tiny code section and you can have people who posted things there over a year ago. You see something there and say Oh cool i gotta try that so you nab that code and try to compile it and it does not work. Mainly because of all the updates since it was posted. But there is no way to contact that person who posted it, so your like ok, now what do i do.

For a newbie that was a very frustrating time to figure out why the code does not work.
But now that i have learned a little bit, i know what to look out for.


#19

@ jdal
Doesn’t the Netduino community suffer from the same problem when there are updates to the Netduino SDK?


#20

The common interest should be NETMF. Unfortunately, hardware guys tend to see things in terms of hardware :wink: