I just posted Create working “minimal” code to prove each module is working on Task Tracker. Feel free to discuss and make suggestions here.
4 Likes
Create working “minimal” code to prove each module is working was updated.
Status went from Proposed to Open.
Priority went from Unassigned to Trivial.
In many cases, these would be in the developer’s guide on the Resources tab for the module. Making sure that they all have one and making them easy to use is a essential.
@ Blue Hair Bob and Brett - something like you can see on https://www.ghielectronics.com/catalog/product/393?
2 Likes
As a relative newbie I found the Resources section attached to ‘most’ of the modules a great aid.
@ John, that’s a great example for a simple module. The reason I originally posted this though was the more complex modules (networking, here’s pointing at you! and cameras) so that newbies or people who have just got the module can simply use that code to make sure their module works rather than everyone trying to give their own interpretation of the code. But please, please, PLEASE! Document what version of SDK the code is for !
@ Brett - Here’s another more complicated one: https://www.ghielectronics.com/catalog/product/322 (Cellular Radio might be better served by an entire document since it has numerous functions.)
Again, that’s very helpful and will prove that the module works and SIM works. May not help a newbie understand why it doesn’t, when it doesn’t, but that at least gives appropriate debug info for others here to trace for that person.
Can I ask - can you also put the framework version not just the SDK version ? “This sample was written using the 2014 R5 SDK, using a Gadgeteer application type and targeting framework 4.3.” And perhaps an expected sequence of output would assist too - here’s what you should expect to see if everything works as intended.
Agree completely! And while you are working at it, provide the references required to have it working. Thats often a problem with code examples as there is no 1-1 mapping from usings to refs.
EDIT: I forgot so say that this is a brilliant idea :whistle:
@ Brett and njbuch - https://www.ghielectronics.com/catalog/product/393 and https://www.ghielectronics.com/catalog/product/322 have been updated. The programs are still rough and only meant to illustrate the sample program feature for now.
Most samples will automatically add the required references through Gadgeteer. But in the cases where I use a special one, like System.Http, that will be mentioned.
I don’t think we need to specify that it is a Gadgeteer application though since all of these sample programs will be Gadgeteer and we link to the .NET Gadgeteer book.
While there were major API changes between 4.2 and 4.3, our goal is to not to that again when 4.4 comes around. These samples should work in future versions as wel. 4.2 is a special case right now in that its API was not updated. That should not be an issue as it is legacy, not supported, and eventually will be removed. All new customers who would benefit from these samples will almost certainly be using 4.3 and mentioning different NETMF versions might only confuse them.
I like the concept, I do, but adding the references like you did (in a narrative) isn’t going to always get the attention it needs. Again, thinking newbie here, if you called out a list of required references to add in a bulleted list it makes it obvious - even if it says “(no additional references required)” in the case where adding the module in the designer does everything you need. Just make it clear and obvious when you do for someone who may not have the background to know to do that.
@ Brett - agree 100%
1 Like
@ Brett - If we notice more than two or three products require manually added references as we add these samples, we will add a dedicated section to call them out.
While everyone loves good documentation I tend to head for CodeShare for examples of how to use some modules and I’ve tried to put some samples in there as well. I’ve notice in some cases links were put in the catalog doc page to usage cases, perhaps that just needs to be expanded.
Create working “minimal” code to prove each module is working was updated.
Status went from Open to Closed.
Sad day 