Forums, a precious resource, handle with care

The Archive Meta
1

I’m amazed by the quality of information available on this forum (and others), and at the phenomena of tech forums in general. It is a new model of technical support; one that significantly cuts costs for manufacturers, and improves the breadth and depth of of information available to users. But what brings this phenomena about? What human drives nurture it? And, what are the threats to a forum’s health and how can it be nurtured?

Those questions have been churning around in my head, and so accept this as an attempt to answer them, and to participate in some strategic way in the continuation and growth of the Particle forum.

Some background, and many of the other gray hairs here will relate. I’ve been working with uP and code since 1977, beginning with an Intel 4004 and moving up through 8080, 8085, 8086 and 8088 and on and on. In 1977 there was no such thing as tech support (unless you were a huge company on Intel’s radar) and there were no forums, but there was a very well written data book. You had to read it, from the beginning, then go back and read it some more.

In 1979 I started a company making educational CPU boards based on the Intel uPs. I did provide tech support by phone, and learned that my best first line of defense was a clear and well written user manual. The products were sold as kits, needing assembly, and coding was done by manually converting mnemonics into bytes and typing them into the uP with a serial monitor.

Next there was MetrByte. We made dataAcq hardware and software for the PC.

Next and last was Measurement Computing, also with dataAcq for personal computers but the software and hardware were getting ever more sophisticated.

In both those companies I personally provided technical support, then managed technical support groups, then managed the manager. I also wrote tens of thousands of pages of user docs. Understand that I do know about providing technical support to embedded products sold primarily to technical people, and the docs and software tools needed to minimize that expense.

Here is what stuns me about this (and other forums). A huge burden has been lifted off the manufacturer by those experts (here called Elites) and experienced regular members who voluntarily assist new users with simple problems, and all users with ligitmately challenging problems. The expense trasference from manufacturer to the contributors is huge and valuable.

Why do they (contributors) do it?

Why would anyone contribute to a company’s bottom line by off-loading their technical support cost, for free?

Other than the occasional tidbit of wisdom gained, and possibly the sense of community, I believe the high quality and volume of forum contribution comes from what Daniel Pink (Drive) identifies as the three most important aspects of work: Autonomy, Mastery and Purpose. Pink asserts that if an organization can provide the opportunity to experience autonomy, mastery and purpose, it will recieve in return an output of quality and quantity of work not possible with other rewards.

Forums are an ideal expression of all three, and I believe the most perfect proof of PInk’s thesis.

Autonomy: Contribute when you want to, as much or as little, and as deeply into your favorite subject as you wish.

Mastery: Forum expertise promotes your personal mission to achieve mastery in a subject. On the forum that mastery is generally recognized in Reputation (Stack Overflow, etc.) or becoming an Elite, here.

Purpose: Problem solving is possibly human-kind’s most natural purpose. Communicating the solution to others is next in line.

With so much to offer the contributors, with such a perfect outlet for the three aspects of Drive, what could possibly threaten to cause contributors to lose interest?

Boredom.

It has been happening on Stack Exchange for a while, and is the subject of much debate there. More and more quesitons are going unanswered and the elite members are expressing more and more frustration with questioners who don’t do their own research, don’t read whatever documentation they have, and don’t search forums for answers before posting.

My opinion is that it will be coming to a Particle forum near you, and soon.

More and more posts are rehashing the same old problems. More and more new users are asking the same questions, and expressing previously expressed frustrations. Experience on other tech forums has shown that eventually, help for the new users drops off.

Particle cannot afford that. It is a commercial venture where every customer counts and you can’t sort out the someday-OEM volume customer from the one-off hacker during the intitial experience. They both look the same from the tech support facing personnel and forum contributors. Particle will lose potentially valuable customers to a company that provides a smooth and well documented initial experience. Providing that experience is something established organizations understand, and why startups are so often not the long term beneficiaries of the markets they pioneer.

It is time for Particle to offer clear, step by step documentation, and not the blog-like web documentation it relies on today. It’s time to provide IDE’s without non-standard naming behavior and other quirks.

For the Photon, the best documention example I’ve seen so far is the new book on the Photon. Sadly, its not even available in the store (7AM EDT 7.13.15). Creating documentation of that calibre is a monumental task, but it is nescessary. HIght quality instructional documention is worth money (sales). I’ve experiened it! In my first startup, I was approached by Hitachi ( and recived a lucrative flow of revenue from them) becuase they were impressed with the quality of the documentation.

The Forum provides Particle an opportunity for a large expense-transferance, but it does so at a price. While Particle can reasonably expect experienced contributors to enjoy contributing meaningful content, it must respond to repetitive and boring problems in the intial experience with a support outlet for those folks at Particle’s expense and staffed by Particle employees. It must create and support the kind of documentation and robust software that minimizes the requests for routine help.

Continued reliance on the forum without a strong improvement in user docs could push the forum toward a morass of unanswered questions from frustrated initial-experience (soon to be not) customers. A problem that other forums are struggling to solve today.

Autonomy is the freedom to contribute; or not.

3 Likes
2

? what is this about?

Try looking for another 6 guys who spent close to 2 years in this forum without fail daily before we start making comparisons

I agree 100% to this. But the funny thing about users is that they don't read/look at the user guide. I contribute my help here daily for exactly what you mentioned and do a lot of work to improve the docs. Still, people swing by with questions where answers are found in the Docs.

Having the interaction and discussion here makes this fun and this is specific to a line of product unlike stack exchange. The community is like an IoT product if you ask me. Things change all the time and new people come and go. I don't see why the forum is doomed. :wink:

Also, take a look here for Docs improvement effort: https://github.com/spark/docs/commits/feature/metalsmith

:wink:

Cutting the story short and changing the title to "Docs MUST MUST be improved" probably brings out the point much better.

3 Likes
3

@Bendrix, I hear where you are coming from and I do agree with the essence that well written docs are a must have better sooner than later, but to state that “forum help [is] doomed” is a bit harsh and would better be addressed to :spark: Particle directly rather than here.

But with this post you stirred up some attention.

So if this post should disappear from here, it won’t be forgotten but taken to a “better afterlife” :wink:

Till then, please allow me to alter the title.

1 Like
4

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.

5

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 :wink:

2 Likes
6

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.

5 Likes
7

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.

8

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. :smile:

2 Likes
9

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.

1 Like
10

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:

https://github.com/spark/docs/tree/feature/metalsmith

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?

11 Likes
11

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:

  1. 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.

  2. 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.

  3. 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. :smile:

12

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.

I haven't been following these issues, so I'll call in @suda (our primary IDE developer). @suda, are you familiar with the issues that @Bendrix has raised here?

4 Likes
13

Yes, every suggestion was noted, some of them are already implemented or had been also raised by other community members.

@Bendrix no suggestion is forgotten :slight_smile: We do our best to prioritize our tasks so the community voice is included.

5 Likes
14

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 :heart: feedback!

5 Likes
15

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.

2 Likes
16

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.

7 Likes
17

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.

Samples:
http://www.seeedstudio.com/wiki/Grove_System
http://www.pcduino.com/wiki/index.php?title=Main_Page

1 Like
18

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!

7 Likes
20

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!

1 Like
21

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.

4 Likes