Arduino forum FAQ?

I originaly started this idea in THIS THREAD.

what about the idea of creating a FAQ to reference to for the forum? that way we could provide detailed answers to the most commonly asked questions, such as "blink without delay". the main details are in the other thread, but what do the GURUs think? it would have to be a collaboration, I think.

~Travis

I had in mind that you would move Reply #5 from the other Thread to here so as to declutter it.

Regarding the FAQ idea Nick Gammon has created a very good Useful Links Thread. However I don't know that those who would benefit most bother to read it.

...R

Rather than do it on Github I suggest that you start a Thread here specifically for your FAQs. That is how I have produced my few tutorials. It makes it much more accessible and allows other Forum members to contribute.

I write my stuff in a text editor on my PC until I am happy with it and then (if it is long) I start a Thread and open 3 or 4 replies (with just "please don't reply something is coming" in them) in succession to reserve space for myself. Then at my leisure I can copy and paste from my text editor into the reserved space. If I find I have reserved more replies than I need I can delete one or two. But with a word-count in the text editor it is not difficult to make a reasonable estimate.

This

even a simple description of why delay is blocking, and why BWoD does not.

may not be simple to explain - but it is worth trying.

...R

travis_farmer: The reason I thought of not doing it as a thread, is how can I keep it useful, without generic comments on every entry from other members? I was looking for information without the "chit chat" so to speak.

I agree that forum threads are not the best way to organize information.

A GitHub repository is a decent idea.

You could use github.io to publish the information as a website using html. In order for others to contribute they would need to submit pull requests or you could give some people editing rights.

You could also do it as a GitHub wiki. This is easier to work with than a website and you can still do a lot using markdown. If you make it publicly editable this will make it easier for other people to contribute information because they can just edit instead of needing to submit pull requests.

But there's no need to reinvent the wheel, there is already a well established Arduino wiki. It's called the Arduino Playground. Not everyone here has a GitHub account, likely more already have an Arduino account. This will make collaboration even easier. There may even be a page on already for this and you could just add improvements to that page. If not you can create a new page. I don't like the pmWiki markup as much as GitHub's markdown but it's not so bad.

Once you have your page going you can create a forum thread for discussion and then incorporate any useful information or suggestions that thread generates into the FAQ.

travis_farmer: I would rather not have the chaos of a publicly available repository.

I don't think it would end up being as bad as you think. The Arduino IDE repository gets a lot of traffic, their wiki is publicly editable, yet I've only seen one case of a non-useful edit over a couple years of visiting that wiki very frequently. That was on an empty page that's content had been moved. It's surprising there's not more spam but I think needing to have a GitHub account filters out a lot of spammers.

travis_farmer: I don't think you need an account to just view the repository, just to contribute to it.

That's correct, I was referring to making collaboration easier, as stated in the very next sentence.

travis_farmer: This thread is kind of that already, just not much information yet.

Sure, just make it formal by editing the first post with a link to your wiki and adding a link to this thread to the wiki.

Doesn't/can't the "playground" serve this purpose?

I am delighted if people feel that my examples, such as Several Things at a Time are useful and worth linking to.

However I wrote them for this Forum and I am not happy about the programs being copied to and made available from another website - such as Github. By all means put a link from Github (or any other website) to the relevant Forum Thread.

...R

travis_farmer: I guess I kind of thought I would get a little more support. maybe there isn't as much of a call for a FAQ as I thought.

Why not try writing a Thread here?

If it gets a bit mucked up you can always pick out the best bits and build them into a Mark2 version.

One thing to realize is that "experts" won't name FAQs because they already know the answer. A list of FAQs has to come from a study of the newbies' questions. You could spend a fun week reading newbie Threads and making a list (that's not entirely a joke).

...R

Take a look at how Robin's 'Several Things' thread is structured:

First there is a warning to noobs - 'The useful information is in the first two posts only. All that follows is noisy discussion'.

Then the current listing of the program.

Then 'official' explanations and notes.

Then the 'noisy' discussion.

I think this is a very useful way to work within a forum environment for developing a consensus document based on a single member's vision. If you have read it all the way through, you'll see that ideas presented in the discussion were incorporated into the 'official' part of the thread - that is, the code listing was updated in the first post of the thread.

You would be able to do something similar with a FAQ. Put together the best FAQ you can, and post it in a new thread. Discussion will follow. As the 'keeper of the FAQ' you would be able to merge the useful parts of that discussion into the FAQ. You will be the only one able to edit changes into the first post, and will have control of what goes into that post. (Moderation notwithstanding.) Build the FAQ in the first post of your thread.

Finally add the warning, identifying the official FAQ part (your first post, and an optional follow-up post) and the 'rabble' part (all the discussion that follows. - it not really rabble, this is where the fine tuning, and consensus happens.)

I believe this would be much more acceptable to the group here than a Github repository. You know - homegrown vs an offsite resource and population. Forum denizens tend to trust others on the same forum more so than the internet population in general.

The key in this scheme is that you are the sole editor if your original post. Once the document becomes truly beneficial, petition the mods to pin it.

I agree with all that @ChrisTenone has said in Reply #16 (and thank him for the compliment).

Just one thing - he says "Build the FAQ in the first post of your thread." I would suggest that you reserve 3 or 4 of the first Replies for your own use.

In the longer term, of course, the FAQ may outgrow the space you have reserved and then it would be easy to move to a second Thread by repeating all the existing FAQ stuff and reserving a few more Replies for further expansion.

I am a great believer in keeping the text as short as possible. Government Ministers prefer to get their briefing on a single page - and there are few subjects for which the essential points cannot be reduced to that size (with suppporting detail available in appendices if necessary). Of course writing succinctly takes longer :)

...R