Putting the Help Files in a wiki?

Paul

Any thoughts in putting the various Help files into a wiki system? This would allow the user community to help keep the information up to date. Or could be locked to certain users. Sometimes it takes me an hour just to find something simple.

Example: SX/B "SUB" was found under "Definitions" not commands. None of the GOSUB..RETURN commands had a link to it. It's called a Directive but it wasn't listed under Directives.
Another SX/B example: TX_str was an example under "READ" not SERIN or SEROUT. A wiki would have allowed me to drop in a link quite easily.

I think the documentation is good..IF YOU CAN FIND IT!..

Thanks for listening.
Paul

Bruce Bates

Paul -

This is more of a question than a comment or condemnation of your suggestion. If such a system were open "to the public" on a read/write basis (with or without supervision), what is to prevent any of the following from occuring:

1. The introduction of SPAM links, porn links, advertizements or other inappropriate entries. See more in Note 1 below.

2. The inclusion of incorrect, biased, or inappropriate factual content. So too presumptions, untested theories or "wild" ideas. See Note 1 below.

3. The changing or deletion of correct/approved content by disinterested parties, whose only purpose may be to distort the documentation. See Note 1 below.

- - -

Note 1:

If this is to be avoided, either all new links and content must be "tested"/approved, or general write access must be limited or avoided. Also any change to existing text might need to be limited to the original poster, as this Stamp Forum has in effect.

- - -

If the Wiki postings are to be supervised in any meaningful way. it would almost take the time and expertise of a Parallax employee (or a Parallax designee) to ensure the correctness and accuracy of said postings. It may take additional expertise in specific applications or "science" areas, to verify or approve any adjunctive information. The thought of a "committee" is worrisome indeed

The idea itself is GREAT, but as is often said "The devil is in the details!".

Regards,

Bruce Bates

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
<!--StartFragment -->

Jon Williams

My concern is the introduction of technically incorrect information that Parallax would be held accountable for; we get a bit of that in our forums and it's work to track down and correct. The title page of our help files asks that suggests be sent to editor@parallax.com -- we do consider those things, though we may not choose to act on all of them.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Jon Williams
Applications Engineer, Parallax

Paul

Thanks for the feedback. It was just and idea I was kicking around after wondering "There has to be a better way". I understand your concerns about the concept. It does seem rather unnerving. I have lots of work information in my engineering design wiki and it's lock up tighter than a drum..lol.

I do keep forgetting about search.parallax.com which is what I should have used to find the information in the help file and other information readily available. I should add a tab to it on my Parallax groups.

I also understand about the incorrect information getting passed around. Not to disparage the forum alone, but I guess I've learned to take ANYTHING on the internet with a grain of salt. I do realize this could be a whole new can of worms. (literally)

That said, a peer review committee could be set up of the "regulars". A report could be generated to the "edtior" just to keep him or her appraised of what was updated, when, and by whom. Most wiki's are suprizingly accurate and can be password protected if need be. To me the wiki form is very newbie friendly for those getting their feet wet in Basic Stamp lore. Sometimes asking a question to the forum is quite intimidating.

I will be sending "MORE LINKS" suggestion to the SX/B help editor very soon. Maybe even a sample wiki.

Thanks again.
Paul

PAR

Jon Williams (Parallax) said...
My concern is the introduction of technically incorrect information that Parallax would be held accountable for; we get a bit of that in our forums and it's work to track down and correct. The title page of our help files asks that suggests be sent to editor@parallax.com -- we do consider those things, though we may not choose to act on all of them.

Ahh, you've touched on a sore point (for me). Parallax sets high expectations in its customers precisely because Parallax provides such good service. Thus-- the sore point...

Technically incorrect information also exists in Parallax's own (free and very valuable!) documents. Timely revision (inc publication of errata) of the documents seems to come very infrequently however ("acting on them" in a timely manner is one part of the process which needs improvement).

Meanwhile, any number of Parallax product users may have noted those errors and sometimes they notify Parallax via the email-to-editor approach, or via the forums (in which case other Parallax customers also can be apprised of the problem documentation, often (usually?) in a more timely manner than seems likely that Parallax editors can provide.

A more useful procedure (to Parallax customers) would be 2-fold:

1. create a forum for Parallax Documentation Issues (Errors and Clarifications), where Parallax product users can post suspected documentation errors (from simple spelling typos to technically incorrect information).

2. improve the "official" Parallax documentation by the consistent use of noting the version/edition/revision level·inside the documents themselves (usually, Parallax does do this), BUT ALSO by posting "sticky" forum notes (in the new forum suggested above)·each time a document is revised. (Parallax customers do not know when/if a document has been revised/corrected, and/or if an errata sheet has been produced by Parallax unless he/she actually visits the Parallax site and physically compares the currently-posted document (revision information) to the one in the customer's hands.

Parallax's already bountiful, free documentation (which includes its powerful forums) could be significantly improved (on the margin)·in its quality and utility·with the two simple, relatively cheap·steps suggested above.

PAR
·