If the info is duplicated then one or the other will be forgotten when updated, as has already happened in the LED topic. If that info is duplicated then why is not all the info in the docs duplicated here in the forum? There is no need to remove everything in the LED topic, the discussions etc can stay, and explanations too. But, where relevant, even the explanations should move to the docs.
Reference info should be in the docs and not have a copy here. Reference info should be referred to otherwise it dies. Best would be for those old topics in the forum made unnecessary by the info being made available in the docs to be edited to point at the docs, and to avoid confusion, to remove duplicated info, replacing of course with a clear link to the docs with accompanying wording. In this LED colours/states example Zach's once very helpful list should now be deleted now it is in the docs, replaced by a link
The general point is that in any answer to a question on the forum, if there exists a relevant section in the docs, that should be pointed to in the answer, rather than trying to hack together an answer on the fly which will have the possibility of not being complete or accurate. If the answer must contain other info then the responder should provide that, obviously, but then should consider if that info too should be in the docs, and amend those accordingly.
@psb777, I agree. As the documentation evolves, it should become the defacto knowledge source wherever possible. I find a lot of new members donāt look at the documentation before posting in the Community.
I thought about thisā¦ because keeping the two sources synchronized is darn near impossible. Iām certainly not going to update every post.
That said, it seemed like a simple but useful update for a post that will be searched for a lot. Iāll add the link you posted there as well, just in case it gets out of sync again. That said, I donāt think someoneās going to want to compare the two sourcesā¦ and if they find discrepancies they will likely just make a forum post questioning the information.
I donāt necessarily believe all questions can and should be answered with a link to the docsā¦ where itās appropriate it does save time, but I do like having a dialog with someone as well. It letās the community know we are here to help, not just tech support copy/pasting info from a manual.
In the case of Zachās post, I didnāt want to stub out his post with just a link to the docs. It just seemed wrong, to me.
This does make me think of a cool idea for the Docs/Forum thoughā¦
We need a search function on the Docs right? Why not extend that to the forum search?
With high level of respect for Spark Team & Elite. I do not consider the Docs as presented an effective means of communicating "A Complete Solution" for any topic. Why go to the Docs just to have to return to the forum to find the rest of the story more often than not.
Sorry, if I seem too critical but, until the docs are expanded for wider topic coverage and more indepth explaination is provided (it will be a big commitment, I know) people will read the first paragraph, skim down to the bottom and head to the forums. And, the reason why ? The forum looks and behaves like a forum. The docs - don't look like a wiki !
@spydrop, perhaps I should clarify. The documentation is not meant to present a solution, you are correct. However, many members donāt RTFM and ask the same questions over and over. What I meant was that wherever possible, the documentation should be referenced first. As for the format of the documentation, wellā¦
@peekay123, how complete of a soluction the docs will be is directly relative to the experience level of the user. I for one am more inclinded to consider that there is a really big bad world out there run by Arduino & Raspberry Pi MCUās and 1,000s of docs to make it possible - Yikes !
Iām only pointing to something that is obvious, āwe need to bring in people who donāt already have a MCUā and you canāt effectively do that with incomplete instructions unless you want to accomplish it as some distanct future date at a Convention Center in San Fransico.
āIts only rocket science when the engineers make it complicateā.
@spydrop thanks for the candidness! Absolutely agree that our resources have a ways to go before they are ideal. Know that they are a work in progress and something that we are certainly planning on working on when we have more hands on deck. Hardest part of a start-up is not being able to prioritize everything
I am in favour of the forum and I am in favour of the dialog.
I am against the info not being in the docs.
If a question is asked and there is any prospect of others asking it, then the info needs to be put in the docs. The forum cannot become the primary place for any of the docs.
It seems nuts to me to give a quick, incomplete and maybe inaccurate answer when one can refer to the docs.
Duplicating the info means it will get out of step, sometimes one will be better than the other, sometimes the other better than the one. It matters not too much which is the better source, the forum or the docs, that it is duplicated means both need to be checked. The correct place for reference info (e.g. LED colours and states) is the docs, not the forum. When someone asks about LED colours and states in the forum, then they should be pointed at the ref. You can also tell them what double yellow followed by puce means, build a relationship, a community, but do them a real favour: Make it that they donāt need you: point them at the ref.
If everytime a Q is asked a quick off the cuff answer is given which neither references the docs nor which is used to update them then the answer is unlikely to be as helpful as it can be.
But those who provide the answers make themselves indispensable if the docs arenāt good. Knowledge is to be shared. What better way than not actually having to be present to dispense it? Write it down. Put it in its proper place. Donāt think you can do a better job of giving the answer than how it is already documented! Or, if you can, then you need to update the docs!
I think the first priority should be to improve the accessibility of the docs. Wiki style, or drop-down sub categories. It doesnāt matter - just so long as you can get to the information you need quickly
Guess how I found out the I2C connection pins? They werenāt in the docs, they were in some guyās random comment about how he had connected up some sensor.
That sort of data must be discoverable within seconds if the docs are to succeed.
Hi @peekay123 - I know that now, but when you first access the docs, youāre in the āGetting Startedā section. There is no indication where you should go to find that sort of information. So I do a search on the webpage and find one non-linking reference to I2C.
I then scratch my head and say āsod it, Iāll look in the forumā. And thatās where I found it. I mean, why would the I2C pins be in the side menu for the data sheet? Surely thatās for purely technical data like the part numbers, etc.
If youāre going to have references buried within non-obvious places (remember - you know these pages very well. Try to put yourself in the position of someone exploring them for the very first time) then at least make the pages linkable, like a wiki.
Try this - go to āGetting Startedā and tell me where I find out how to change the SPI clock divider. OK, nothing on that first page. Where should I go? Nothing on the side seems obvious. OK, searchable forums it is.
Okay ! That's now Two of us who have said the very exact same thing now about "Wiki Style" & " Sub-Categories". See ! I am not a loner in being candid abou the truth. (No pun intended Steph)
If you throw all your nuts in the same bowl how hard will it be to find your favorite nut? Almost impossible ! (but again my name is bobby
When i first started off, it took me a week to realise that there were sub-headings that would change in the LHS column of the docs - though they were right at the bottom! (learning that helped a bit, especially in the firmware section).
Secondly, as a newbie, if i wanted a big list of commands - I'd never think to look under 'firmware'. I found that out only via the forum!
Maybe look at how other guys (arduino etc) model their help/docs and build on that? The info in docs is great, it's just hard to find - and most people give up on searching pretty quick.
Two more things :
code snippit / examples in the docs are confusing for newbies. All caps headings look like code, and if possible please provide a super short ACTUAL example.
the forum consistently out ranks the docs on Google search results, and that's why a lot of people end up there. Maybe a banner / notification the first 5 times a newbie tries to post on the forum saying "did you search the docs (link)" would help the situation? Maybe even always show that to guests?
So i had posted that from my mobile, without actually looking at arduino's page.
I just looked at arduino's page, and then back at spark's docs - and here's a very simple change-around that i think would really help:
Changes:
The "firmware" page is the landing page.
It has been renamed to "Language Reference" (or "Commands" or anything less threatening/confusing to n00bs).
Split the list into 2 columns and also added some padding above headings to visually separate them better.
There is a search functionality added (for within the docs).
The complex / confusing sub-menu structure of the LHS column is removed.
Sub-menus should DEFINITELY be removed on the landing page, and perhaps also on other pages (because it becomes information overload, and in reality, its just a "scroll to" link for info that's already being displayed in the RHS pane).
