The title change is your prerogative. As for deleting it entirely, that would just be a great way to ensure that Particle does not benefit from a debate on the subject. As for addressing it to Particle directly, that is well served here, where other forum members can either agree in essence, as you did, or not.
Seeing as this is regarding the elites, I thought I’d chime in as well. Being on the forum has always been a lot of fun, and we wouldn’t continue doing this if we didn’t feel like it was.
I mean, @ScruffR has been helping the hell out of people so he could become an elite (which he definitely deserved ;)) Even though he’s been around since the early days, he apparently felt it was worthwhile spending his time here.
Personally, I think that as long as we can help people, and make a difference, we’re okay. The occasional “read the docs” or “read the forums” is to be expected. Heck, most questions could be solved with “do a quick google”, but where’s the fun in that ;)? You might as well say “study electrical engineering and fix it yourself” (which is what I’m currently attempting…)
Mind you, I do definitely agree that we need to improve the docs, but then again, I know that’s happening already. With the release of the photon, a lot of resources got pulled into that, which I’m sure will be relocated to things like this as soon as the initial issues are fixed. If we (elites/champions/helpful folks) can help bridge the gap between the forums and the docs, until they’re ‘upgraded’, I’m cool with that.
Believe me when I say this topic will be picked up by particle whether it remains here or not. I’d personally agree with @ScruffR to direct it directly to Particle, or perhaps through a joined elite/particle PM. I don’t really think we need a public debate here since most of your points are really valid ones which require no debate, but rather direct action. Do the docs need an overhaul? Hell yes! Seeing as Particle is already working on that, I think they’ll agree with you on that as well. If your goal was to help the elites to not get bored, don’t worry, we’ll manage
What we really need is a WiKi that includes devices by name and how to hook them up, with tested compatibility! No discussion, just concise info to check. Basically a RTFM for devices that we may hook up to Particle units. Something to consult before asking for help on the forums.
Often when reading forum topics on specific hardware that I may want to use, by the time I get to the end of the thread I am more confused than when I started! So I post a question to only be told then that the particular hardware was discussed somewhere else, most often in a thread that started up on a topic that had nothing to do with what I am looking up in the first place!
I would like to see a ‘go-to’ place listing hardware compatibility, software ‘add-ons’ needed (primary and secondary libraries), and how to hook the device up just enough to prove it works and have a confident starting point.
The post was directed not just to the Elite contributors, but to all contributors, of which there are many. Elites bear the brunt of the work, but there are many hands in the forum.
And I disagree. Particle will benefit from hearing what all the forum participants have to say on this subject. When a company only talks and listens to insiders, it often heads down the wrong road.
I am a very kinesthetic kind of guy so it would be great to link to examples of the types of suggestions made here. If something like this is done in Arduino or other land, it would be great to see how.
Apart from the fact that I’m not a fan of a wiki (we’ve had some really heated discussion about that in the past), you do realize it’s virtually impossible to list every single device out there? There are simply too many. But since most work with similar protocols, I2C, onewire, etc, some general explanation is often possible. There’s often documentation for the part that’ll let you know how you’re supposed to use it.
That’s not to say it isn’t a good idea to start providing ‘easy’ examples for common parts. Would that be something similar to Adafruit’s learning system perhaps? I’d prefer that (a lot more) over a wiki. Like @peekay123 mentioned, existing examples would be appreciated. No need to reinvent the wheel.
Hey @Bendrix - I’m going to put aside your incendiary approach in this post (which I do not condone, and I will address in a private message) and try to address the primary content and criticism, which I do agree with.
If I were to summarize your post, you said “we need clearer, more complete, better, organized documentation”. You are correct. The team is currently undergoing a major refactor of the documentation, which if you want to follow along, is on the
feature/metalsmith branch of the docs repo:
You can see specifically what we’re working on in its Pull Request:
The rebuild is still very much a work-in-progress, so it’s a good time for feedback. What specific changes would you like to see in the docs that we could consider as part of this refactor?
Hello @zach - Thanks for summarizing my post, but no, that was not the message. The message was my thoughts, based on observation and the thesis of a book I respect, about why people donate so much of their time to what is another person’s bottom line.
Based on the theory presented, I wondered what might encourage or discourage enrichment of that valuable resource. Given that other forums have experienced problems I made very specific suggestions to Particle that I think will help keep the forum vital. Those are:
Establish a first tier technical support team to help the new users that are struggling to become successful Particle users. Call them unwilling to read the docs, or just needing extra help; call them what you will, but be available with help when they call on you because leaving them to the forum will not help the forum.
Create high quality initial experience docs. I suggested the recent book, Getting Started With The Photon as an excellent example of what initial experience documentation could be. I suggested once again you carry it, a suggestion I have made twice before in the last many weeks.
Sove the problems with the IDE that result from non expected behavior, or requirement of extra steps not required in other familiar IDE’s that if not done, result in failure. I’ve made this suggestion in several places both when asked and when helping Particle customers.
Finally, I pointed out that Particle could be losing valuable customers during the initial experience if they become frustrated, and that makes them available to a competitor. The forum is a great way to get help to customers at no cost to Particle but in doing so Particle loses a key resource because it is loosely coupled to the customer.
When a company offers the first line of technical support, you get the opportunity to do much more than provide support, you get the opportunity to learn about the customer, the application and the potential for volume sales. That is the main benefit of the closely coupled company provided support. My experience is that the value of the actionable information far outweighs the cost of getting it.
Examined for content, you’ll see that my post is 100% directed at encouraging Particle’s success. The time and thought that went into it should also be respected. Incendiary? If you say so. But I’ve been told several times, and to my own benefit, to light a fire under my backside and get to work.
Thanks @Bendrix. Here’s where we are on each of your suggestions:
We have hired a new customer success team (@jonlogan and @corey) that is currently ramping up. They’re currently focusing on helping start-ups deploy their products behind the scenes, but they will be spending more and more time providing support here in the forums (especially @corey). I agree this is a need, and it’s something we’re currently investing in.
Fair criticism, and @christine is working on a major content refactor to the docs that will, I hope, significantly improve the onboarding experience. This is part of what I linked to above.
@Bendrix no suggestion is forgotten We do our best to prioritize our tasks so the community voice is included.
I would also like to add that many of us at Particle frequently read and post replies on the forums personally, which definitely helps us learn which issues are currently the hottest and which successes are most well received. We feedback!
I give hearty approval to @Bendrix’s idea, although I am also fully aware of the extra work required to update the documentation. My 2¢ on this is that not everyone (or at least not me) might be aware that the Particle line is based on the Arduino library. It took me awhile to figure that out (via the forum)…and then longer to figure out the proper way to handle C char* arrays. Admittedly, after I figured those things out, I was spending a lot of time searching for C reference on the web, which answered a lot of questions. Personally, I’d at least appreciate a link to some good Arduino docs…
There seem to be a number of hidden functions–or at least they aren’t in the documentation, such as TCPClient.status(). I can find references to it on the forum, but no documentation as to what it actually does!
Yes, I’m fully aware that most people don’t read documentation…but I beg to differ. I’ve programmed Microchip PICs for a number of years now (always in 100% assembler ;-)), and the datasheet was almost always all that I needed. (Admittedly, Particle is the first dev platform on which I’ve joined the forum.)
Please note that I’m not complaining. I am so happy for Particle with all they’ve accomplished. I am fully aware of the multitude of difficulties surrounding not only creating a project, but much worse–bringing it to market, and dealing with the barrage of questions, mine included.
Hi, all. Thanks for all these comments, I’d love to go over a bit what we’re working on in the docs currently.
You can play with the actual functionality as we update it by going to the github repo, but here’s some highlights:
Content reorganization. We are consolidating a lot of the info we’ve kept in disparate places into one searchable location at the docs. This will include:
- Start-to-finish guide. We want someone with basic knowledge of arduino to be able to use Particle super easily. We want to provide something where you can start from the beginning, read to the end, and feel enabled to go out and build what you want to build. We’re organizing a section of the guide to do exactly this. To start, this is going to be a guided reorganization of some of the content we already have, but we hope to develop this with more examples and guided lessons. Currently we have a section for getting started, a section on tools and resources, and a section on how to build a product that has content similar to the Prototype to Production blog. This entire section will be outfitted to be easily navigable and readable, with nice scrollspy and fwd/backward arrows, and some small CSS customizations for images, videos, and footnotes.
- Reference Section. This will have all of the info currently in firmware, api, mobile, etc. Anything you might want to reference dictionary-style, instead of reading straight through. The nav bar is collapsible so that you are able to be in one section of the firmware docs and click through to find other sections that you may need.
- Datasheets. Hardware datasheets will go here.
- Support Section. Reorganized and more navigable and updated version of the content currently living on http://support.particle.io. Because this will be a part of the docs, everyone will be able to make pull requests to this page to update/add articles on new issues you’ve seen and solved.
Core/Photon Switchability. Although this currently exists, it’s pretty difficult to navigate and edit. We’ve made some changes we think will be really helpful here, both in terms of URL structure and the actual build of the page.
Comprehensive Search Bar. Because the content will be organized in one place, our search bar will now be able to give you results from any of the pages in the guide, reference, datasheet, or support sections. The first release of this search algorithm will probably not do exactly what we want it to, but we are now using a search system that is more customizable, and we think ultimately that we will be able to make it give really great and specific results.
I highly recommend that, if you’re interested, you check out the current branch we’re working on on github. Keep in mind that it’s still very much in development, but ping me or @jeiden with any questions, comments, or issues. I’d especially like it if you’d point me to particular tutorials you like, features you think are important, or things you got stuck on in the current docs that you’d like improved.
I agree with @Bendrix, a detailed documentation is necessary for success. But I think particle.io is not IBM, is a startup. I think the best approach to achieve this is a wiki, I saw these times many startups use these tools to start and mantain the documentation of their products. This has the benefit to get feedback from community and get published always the last version.
I suggest the wiki from https://www.mediawiki.org used by wikipedia, is open source, well known, easy to use.
For what it’s worth, as a non-employee nor an elite didn’t take @Bendrix original post incendiary or in bad taste, albeit passionate! You do make some genuinely accurate observations about how a technology company is to support the launch and implementation of it’s product. Unfortunately, there is no silver bullet to accomplish that task 100% successfully. As you and other replies have said, and we all know it’s true, it’s easier to post a question and get an answer than read docs. Maybe that problem is perpetuated here at Particle, because newbs have figured out that it’s instant gratification, this is a very fast and attentive forum! But not answering those newbs questions perpetuates frustration and loss of customers, too. The Intel chips you mentioned had gigantic, cryptic datasheets written by the company, I doubt there was a lot of examples in there. While I do hope that there are products being developed on Particles, I’d guess the biggest audience by far is Makers (90%?), not engineers, who are going to read hundreds of pages of documentation before fiddling with their device. And you can bet that if Intel could have created a passionate community of forum users back then, they d@mn well would have!!! Improved documentation would help everyone, but newbs will be newbs, Makers will figure it out, engineers will complain about the lack of corporate reading. I’m very thankful that Particle is trying their hardest to balance documenting their arduino based products, and that we have Photons and soon Electrons. If this rather small company devoted the time to documenting every nuance (and again, it’s arduino, plenty of self help out there already!), then I imagine their demise would come quickly from not bringing out the Photon and Electron. The number of tech writers at Intel in 1977 probably dwarfs Particle employees.
Again, I don’t disagree with @Bendrix points, but these are challenges of many companies releasing products that don’t just work out of the box. Efforts by Particle to improve initial experience are visible since the launch of the Core, and show genuine commitment on their part to succeed. And these forums and Elites have been helpful to me and seemingly very healthy to this product line. Keep up the good work, Particle, and @Bendrix, please continue to contribute as much or as little as you want to the forums!
I love wikis in concept, but in reality they too often fall into disrepair (there needs to be a TON of activity to make them self-sustaining). Our documentation is designed to be a nice compromise between something that is actively managed by the Particle team and that can accept contributions (all pages in the docs are editable, edits are submitted as pull requests to the team, so we and the Elite can maintain the quality of the documentation).
As I mentioned earlier we’re working on a huge docs refactor, which will be available next week. Once that’s out, I’d encourage people to look for holes in the docs and contribute edits to help us plug the gaps! The purpose of a wiki is to allow the community to contribute, and you can do so at any time!
Thank you @brianr, for understanding the intent of my post. It has been a demoralizing experience, to have attempted to bring forth for discussion an interesting psychological theory (Drive), a real phenomenon (Tech help forums) and a company that I care about (Particle) and how relying on a forum for tech support can both aid, and potentially hinder, that company.
For anyone who doubts that forums face real challenges as the weight of initial-experience questions grows, I encourage you to listen to this podcast entitled The Decline and Fall of Stack Overflow
This quote is telling, and sums up the podcast’s issue statement quite nicely.
"Essentially, we are scaring legitimate, thoughtful people away from getting help. That’s one side of the problem. Additionally, some of our best users are getting more frustrated than we want them to be and (importantly) expressing that it’s hard for them to find questions that they want to answer. "
That podcast, and a series of PM’s from one of the Elite on this site put me to wondering about the health of the Particle forum, and if it too might face some of these challenges. That particular Elite expressed his growing frustration at answering questions posted by people who don’t take the time to do their own research and work before asking questions. Sometimes his answers to such posters are more of a ‘go back and look at such and such’ rather than an answer.
Stating these facts is not being judgmental, nor condoning nor condemning the actions. It is merely a presentation of what exists, so that a discussion might take place. I sympathize with that Elite’s position entirely. Autonomy, Mastery and Purpose are not so fully satisfied by a parade of repetitive questions. Even purpose, that of helping a community, can lose its luster if asked too often to help those who appear not to help themselves.
On the other hand, while that is a valid position for a volunteer, it is an unwise position for a company to take. A company must embrace all customers and find a way to satisfy and nurture them. Paid tech support people cannot choose whom to help, nor punt back directions on how to find help on your own. I’ve run tech support in three companies and know for a fact how much business begins with a technical question Often it is a question that the customer could have found on their own, but today, she just wants you to provide it. If you’re paying me, as Particle’s customers pay them, then OK.
So it is this part of the technical support process (initial-experience) that I was asking the question of; has it reached a volume which is not reasonable to place on the forum?
As several members have pointed out, the forum is a great place to get technical help, and a challenging place to find technical help. If you are working your own thread, or accessing a clear and obvious and short thread, you can get what you need by reading forum threads. However, if the thread is long, complex, taking a long time to develop into coherent questions and solutions, then the forum is a very difficult place to get help. Clear documentation does a better job of that and will offload some of the simple repetitive question from the forum. In that regard, rather than ask a question, I opined that Particle needs to step up. @zach has explained that the process is ongoing and to expect something wonderful, very soon. Bravo!
A number of members have asked for a wiki and Particle appears to be opposed to the idea on the grounds that it may not in fact be beneficial. The book Drive, which I encourage you to read for inspiration, uses as example of its ideas the experience of Wikipedia and Encarta. Remember Encarta? Microsoft’s answer to the encyclopedia? It was going to be the world’s most popular? Remember when Wikipedia launched, and nobody thought that an encyclopedia contributed to and maintained by volunteers would be popular or even have much content?
Encarta failed. Wikipedia did not. Is it perfect? What is? I tell my kids (contrary to their teacher’s instructions), go ahead and use Wikipedia, but recognize that it can be wrong. If you are relying on something you read there to make an important decision, you also have to read the citations and check them. So, I ask, how is that any different for a Particle Wiki? Will it be perfect? What is? Will it be helpful? Will it be built and maintained by the same passionate volunteers that contribute to the forum? Of course. One is compelled to ask; if the community can’t create a useful wiki, then from where springs the forum?
Finally, in the blistering private message I received in response to this post, and its claim that it represented the tip of a spear composed of most of the Elite and Particle team, let me assure anyone who took offense that the initial post was not designed to incinerate anyone. Who would waste their time doing that, and why?
The purpose of the post was to reflect on an amazing phenomenon, explore its roots and motive power and to consider how to nurture it. Part of nurturing is removing obstructions as a gardener removes weeds, and so those are also worthy of discussion. Most important of all, the Elites were singled out as singularly affronted by the ideas in the post, and that is a mistake. While I respect and value them for their extreme contributions, they provide but a part of the value of the forum. The post was aimed at helping Particle and all the contributors who provide innumerable hours of free effort to help us. The forum lives because it provides what we value most; Autonomy, Mastery and Purpose. Nurture that environment and weed out what threatens it.
@Bendrix… I’m too new to the Forum, so I can’t PM you, unfortunately. But very interested in your points and would enjoy private discussion. Please PM me or reach out on Twitter @CosmicPuppySF. Thanks!
(Pardon the interruption, everyone else… I definitely find this thread and the Forum very informative, but not much of a contributor here yet. Find me on SmartThings Community though if you wish! @tgauchat).
For a start-up, we’re impressed by how much the Partcle team has gotten done (we know, being a start-up ourselves).
The reason our company chose the Core and Photon was because it was so damn easy to use… no questions required beyond the docs, forum history, and Google. Sure, the docs aren’t perfect, and forum answers get long-winded, but we had the firmware compiling in < 30mins and flashed in the Core.
I mention that because there are a lot of us silent users who have no problem… no apocalypse coming