@psb777, I’ll try to get on that documentation tonight.
2 Likes
Thank you very much. I appreciate much work done in this regard is that of volunteers, and I’m unsure as to your status on this project. There is of course no overnight fix to all the documentation issues. While I am being this presumptuous, this annoying, may I venture to suggest that the issue is cultural: developers must deliver at the same time as their code at least technical documentation to the same scope as that provided in the traditional Unix man pages. A proper function prototype is needed. A proper brief English text synopsis. Each parameter must be fully described. The return codes too. Any side effects need to be described. Blocking/non-blocking. Limitations. Resource implications. It seems to me that sometimes no technical specification has been written. Such tech spec would ordinarily define the API to be used, and that might mean that docs as I describe would exist prior to coding starting, it would be a spec against which to develop, and to test, rather than being docs which have to be reverse engineered by some willing 3rd party such as @peekay123 months later.
I think the reason this was not doc’ed is because the Arduino Wiring language does not doc the return codes from these calls. Almost all of the wiring language code is doc’ed this way: TCPClient, TCPServer, UDP, etc. I am not saying that is right or wrong, just explaining why the Spark might have chosen to doc it the way they did, following an existing “documented” API.
The problem of calling udp.stop() immediately after udp.endPacket() is just speculation on my part. It seems like a potential problem since there is no safety interlock in the code, but some folks have done it successfully. I would categorize it as a best practice to avoid calling stop immediately after sending.
All of the elites are volunteers although some former elites have been hired by Spark now.
1 Like
Definitely keep reporting Doc deficiencies over here: https://community.spark.io/t/documentation-needs/4555
2 Likes
It has previously argued by others, when I have made this point before, that documentation to the level I suggest is neither wanted nor is it appropriate. I would like to think few would argue that now, now that many thousands of Cores exist, and the next iteration, the Photon, could be about to take the IoT world by storm.
@psb777, I am working on documenting the return values for the UDP class for now as I have limited time. However, I can’t vouch for the blocking/non-blocking nature of the calls and I hope other members will pipe in. I don’t want to make the changes to the docs yet so perhaps posting a readme on my github is the easiest thing for now. @BDub, @bko any ideas on that?
As a possible quickfix for missing docs, which would need more time to put together, I’d be happy to accept a link that would forward me (or people who don’t know about the Open Source repo) to the respective github files (e.g. under the heading WiFi add a short paragraph to list the respective files)
While this should not mean that there would be no need for a verbal documentation anymore, it would at least help mildly adept programmers to find out what a function does, expects as parameters and willl return.
After all Spark still is a relatively “small StartUp” with a tremendous amount of burning topics on their ToDo and a lot of the Elites are volunteers that do have other things that need their attention, too.
But even with major players on the software front you don’t always get a documentation that deserves the name.
For one of the projects I’m involved in, my company has commissioned some SW (850K+ Euros) with a global player (360K+ empoyees worldwide) but the official doc status is Feb. 2012 (!) because external changes (by law and regulations) called for permanent adaption, extension, … so the docs can’t keep up, but as we NEED the SW to work, we agreed to only get doc deltas and informal updates rather than let the dev department be slowed down by the doc department.
Given this experiance on a professional scale, I’m quite impressed with what Spark has achieved and I’m willing to turn one or two blind eyes to the temporary gaps in the documentation - after all for me it’s more a hobby project and private interest, and I guess there are only few who build their economic existance on the Spark Core and it’s doc status.
But to be clear, even for a great product it can be said: The better the documentation the greater the acceptance of a product and thus economic success - and Spark definetly is aware of this and does have it on the ToDo’s, but there is a desperate call for more hands in the game.
For my part, I’d like to contribute more to the project (so far only two doc PRs and two SW PRs), but as said, there are more important things that need my attention, too 
3 Likes
So, development on that project occurs without technical specs? 
Yes, of course What else?
No! Whenever new rules and regulations or real life experiance call for a reevaluation of the previous specs, that is done in-house first, then forwarded to the contractor, then discussed together and if neccessare refined/modulated and finally indentured and commissioned. All this is documented in our project monitoring tools.
But that’s the point. There are different kinds of documentation.
The one I described above is the concomitant documentation - for Spark this may be in the shape of this forum and the Open Source repo - which does put in writing changing needs, modifications to previously agreed but outdated specs, work in process, …
And there is the final “Manual/Handbook” documentation that has its own - or several - mileston(es) in the project plan, without which the product will not be accepted and payment will be withheld or contractual penalties may be applied.
But these documentation milestones are usually set after individual project phases have been finished and consolidated.
For Spark I’d see some doc milestones already reached and fulfilled and others not (yet).
Yes, many things are documented; but some things are not. As I see it often the last step is not being taken. A learned Sparker provides useful and necessary help here, in the forum, and this is not then folded into the docs.
An example from yesterday: I bricked a Core and it needed to be resurrected with dfu-util. I could not remember exactly how and what. Fortunately someone else had exactly the same problem, same time and posted the question. It was top of list when I opened the forum to search for the answers. Someone had already quickly responded with a dfu-util command not supported by dfu-util on Ubuntu. I tried to find an Ubuntu repository with dfu-util 0.7. Hmm, I would have to compile from scratch. I search the forum for my error message. dfu-util 0.5 advice was found. I got there in the end, but the process was much longer and more involved than necessary, and longer and more involved than I describe!
As always, in the forum there are 27 answers and not one of them is quite correct and complete. Some of them are not helpful, one or two are plain wrong. This is no one person’s fault - all are attempting to contribute - but the nature of the forum is such that you cannot edit my fairly good answer to make it more correct - all you can do is comment. Any correct answer in the forums is rarely 100% correct 1st time. Info from two or three comments and two or three threads needs to be conflated-aggregated by the reader.
That is and always will be a problem with documentation said to exist because it is in the forum. Yes, it’s there, somewhere, in many comments, several threads, less good info needing to be filtered out, by the reader; contradictions needing to be resolved, by the reader.
The solution might be for Spark.io to encourage us to fold info from the forum into the docs. [They have provided a mechanism to do so.] Or to do so itself.
Countless examples show this often never happens.
1 Like
As much as it hurts - you are rgiht there
More docs would be much needed - so please to everybody: “More pull requests for docs!”
I’ll try again, too 