Sorry @Ben, but here is yet another thing the SmartThings team needs to address…
The size of this group has nearly tripled in the last few months… Congratulations! But with new users come new questions, or more accurately, the same questions over and over again.
This is a great community, but you know as well as I do that eventually folks will get frustrated by seeing the same old question being asked by every new member.
Do you have a plan to address this?
A knowledge base maybe where we newbies can first check and then shoot a question?
Also a “best performant devices with ST”. Probably may not be run by ST as it may offend partners.
Just my 2 cents.
There is such an animal, but it is not presented in a manner that directs folks to the answers they most often seek. For instance, how to install a Smart app that others have posted/linked to. This is one of the single most asked question here, mostly because there are very few published apps, and the real meat of the platform is in the sample apps of the IDE and code posted to various forum topics.
Things like this need to be A LOT more obvious than they are; a pinned FAQ would do, IMHO.
I completely agree with Scott that the KB needs to be ripped apart and put back together. If ST is shorthanded to do it, perhaps they could open it up to a few community members to populate? Another idea - off a flag/tag that regular users could use when a thread looks like it could be added to the KB (edited, of course).
I’ve always thought a wiki would solve a lot of problems with the documentation, so I went ahead and made one.
http://www.haudenschilt.com/smartthings
Feel free to add anything.
Ben’s off on another planet for a few days so I wanted to address this to the best of my ability. In short, yes, we have plans to offer better resources for our developer and tinkerer friends - especially new folks as they’re jumping in. A good part of that has been increasing the size of our Community team (@mager).
We’ve been looking into better documentation tools and resources. It’s very likely that in the near future you’ll start to see some of that content pop up here on the forums.
You can see an example of some of that content here. I’m definitely interested in what you think of it. It’s actually already out of date as we’ve added the “From Code” option when creating a new SmartApp.
Ok… I’ll weigh in. First sentence is off-putting: “SmartThings developers can”. Many new users won’t know what a SmartThings developer is; or that they can become one with a few mouseClicks. They only know they are not one, and will be stopped in their tracks right there.
While this documentation is accurate, it needs to be friendlier. And discovery is just as important. Short of putting something in the box that says “Visit XXX Sex - Free Porn Videos at XXX.com for tips on getting more out of SmartThings”, it needs to be presented in a place all SmartThings users come to for more info. If that is the top page of these forums, sobeit. If somewhere else than put it there.
BTW, I am not sure I see an option for oAuth in the “From Code” tab. Is it offered further down the process?
Not sure about the oAuth. @mager or @urman may be able to chime in.
The documentation I shared is definitely still being drafted. We’ll revisit some of the language that you mentioned. There’s also an intro to these little guides that describes the process to become a developer.
Great points @scottinpollock. One of my goals is to redesign the developer website to be more friendlier. The documentation is thorough, but coarse and overly technical. I want to build practical examples. I want to capture hacks from the community, even if they aren’t officially SmartApps.
Also, those tutorials Tyler posted are great, but they don’t explain why you would want to build a SmartApp.
I also really want to have a public-facing website for SmartApp discovery. The SEO alone would boost the developer community.
Would love to hear more of your ideas. Let’s build it together.
Hmm… I see lots of discussion here about developers, but not so much for end users. It seems like there needs to be two areas - one detailed, technical area for developers and one simple area for regular end users.
With HA hitting the mainstream now much more, people “just want things to work out of the box”. The current support site is a good start, but it is a bit cumbersome to find what you need. I’m going to think of a few simple scenarios and then go through the current site to see if I can easily find them so I can give you some real world examples.
Yep
And yet, not technical enough. I would still like to see full API docs. A list of every available function and arguments. The kind of thing that is generated from code. Comments and such would be nice, but just knowing what is available would be useful.
I also don’t think a “regular end user” / “regular customer” should have to use the forums as a primary source of information. The forums should be a secondary source, for when they have gone through the support site and could not find an answer or they did the steps and still have an issue.
I’m an IT professional and I research problems on the internet all day. I use forums A LOT to find answers. However, I’m good at it because I have been doing it for over 19 years. I know how to sift through the chaff to find possible solutions. That can be hard for someone that is not used to it.
We should definitely have a “process” where when we see a question repeatedly asked on the forums, we can escalate it to ST to get it added to the support site.
(I just reread this and realized that I come off as a bit snooty in the second paragraph. Sorry about that…that is not me at all!)
Hey Andrew…
I have spent the last 16 years designing and documenting a development tool for non-programmers, and it is possible to offer the code savvy the scope they need, as well as making it all understandable to the non-coder (where easy discovery within a centralized body of information is important).
We chose to do this in two parts. The first is an overview, which reads much like a book, discussing how things work (the big picture, objects and their common properties, events, event handlers, operators, commands, and functions).
The latter is a language reference… searchable (in a number of ways), categorized, cross referenced, with an entry for every token in the language (1370+ at this point), each with multiple syntax templates and syntax examples (showing variety of usage), and a full description of the use of that token along with any possible caveats and limitations, with links to related tokens. They are all categorized by type/class, and by applicable objects (in the case of properties), as well as by concept.
While much of this info is presented on the SmartThings web site, it is all written by programmers for programmers, with insufficient example syntax, and no granular reference; leaving the java/groovy uninitiated to search online for the proper notation, which provides even less helpful results (many of which don’t even apply to SmartThings’ implementation of groovy).
Add to this the (lack of) speed, and the tediousness of the IDE and you have an environment where you would like to avoid trial and error at all cost, but unfortunately, this is the default learning curve in its present state. While all of what I have created in SmartThings works, there are pieces in many apps I see that I can only guess at their nature because they are not clearly documented anywhere.
See my post tagging you re: sendEvent.
I have asked enough questions on this site to conclude that there are a very precious few who know the answers, and this means they are simply not published, or if they are, even your devs can’t find them.
I realize that this is not trivial, but IME, it pays for itself by increasing adoption and lowering support costs. Plus I’m available! (c;
Good point. But don’t you thing those classifications have a lot of crossover?
I really don’t like that word ‘developer’. Most of us here are users, yet very many have pasted someone else’s creation into a SmartApp or device-type and made changes to address their needs. Are they users or devs?
Of course there WILL BE those that never venture outside of the mobile app, and improvements need to be made there. But when those ‘users’ need additional help to discover which SmartApp or Hello Home combinations they need, I’d hate to have the initial “user” documentation/site be devoid of a very big part of what SmartThings is, and have them have to go digging for in case they ‘might’ be interested. Plus if we ever accomplished the documentation I envision, many would see it isn’t so hard and would want to dip their toe in the water just for grins(whereas now it is a PITA).
I’ve said all along that a certain part of that needs to be in their face from the beginning. If you need a minivan, they don’t shuttle all of the sports cars off the lot when you arrive. They’re still sexy, and may tug at your heart strings as you walk by. SmartApps are sexy, or at least the fact that you can easily (well, someday) shape them into practically anything you want, certainly is.
Thanks @scottinpollock, this is great. I’ll take it into account when renovating the docs.