Solving The Documentation Problem - Opinions Please
Wossname
Posts: 174
The Propeller 1 has a big problem: some of the more exotic documentation is gradually being lost. Devoured by the internet over time.
We have seen numerous blogs, wikia pages, random links to very useful information simply vanish.
If we are lucky, one of our members here has a copy stashed away for a rainy day and is able to re-upload it for all to use. Lucky.
In some cases the documentation had never existed at all(!) until an enthusiastic Propeller devotee did the hard work themselves and
created it for the benefit of all. Most All of my Propeller projects would not have existed without the hard work of others.
It seems to me that we currently have no reliable storage method for making this fragile information available for years to come.
If one wanted to keep an important code sample safe for many years then this forum certainly would not be a good place to put it.
No offence meant to Parallax, but threads have disappeared over the years and with them useful resources.
So? ...
I'd like to invite anyone interested in creating some sort of robust "knowledge base" for Propeller, to give opinions on how to achieve a solid, long-term information repository to reply to this thread with constructive ideas.
If anyone want to volunteer some of their time to discussing how this can be achieved and putting it into practice, then this would be most welcome.
What information do we need to keep safe?
Advanced topics only (to begin with). Not things like "how to blink an LED".
I mean things such as the following, which require extremely detailed and unambiguous coverage...
* How does the Spin Booter work?
* How does the Spin Interpreter work? (this is a HUGE topic!)
* How is PASM code inserted into the Cogs?
* 3 Bit Protocol for downloading a Spin/PASM program to a Propeller system.
* Why does the Propeller need 4 clock cycles per PASM instruction, what's it using them for?
* How do you synchronise two or more cogs running Spin or PASM?
* Why does the video generation work the way it does?
* Why do birds suddenly appe-... nevermind.
We also would greatly benefit from peer-reviewed tutorial content. Especially for the really difficult stuff.
Epilogue (or, this post is way too long already)...
I don't have any answers to this problem right now, but I want to help preserve this information and I need your help.
In another thread just now:
This is true, we are wasting energy having to recover old files that are simply not backed up anywhere. What a silly situation.
Thank you for your time.
We have seen numerous blogs, wikia pages, random links to very useful information simply vanish.
If we are lucky, one of our members here has a copy stashed away for a rainy day and is able to re-upload it for all to use. Lucky.
In some cases the documentation had never existed at all(!) until an enthusiastic Propeller devotee did the hard work themselves and
created it for the benefit of all. Most All of my Propeller projects would not have existed without the hard work of others.
It seems to me that we currently have no reliable storage method for making this fragile information available for years to come.
If one wanted to keep an important code sample safe for many years then this forum certainly would not be a good place to put it.
No offence meant to Parallax, but threads have disappeared over the years and with them useful resources.
So? ...
I'd like to invite anyone interested in creating some sort of robust "knowledge base" for Propeller, to give opinions on how to achieve a solid, long-term information repository to reply to this thread with constructive ideas.
If anyone want to volunteer some of their time to discussing how this can be achieved and putting it into practice, then this would be most welcome.
What information do we need to keep safe?
Advanced topics only (to begin with). Not things like "how to blink an LED".
I mean things such as the following, which require extremely detailed and unambiguous coverage...
* How does the Spin Booter work?
* How does the Spin Interpreter work? (this is a HUGE topic!)
* How is PASM code inserted into the Cogs?
* 3 Bit Protocol for downloading a Spin/PASM program to a Propeller system.
* Why does the Propeller need 4 clock cycles per PASM instruction, what's it using them for?
* How do you synchronise two or more cogs running Spin or PASM?
* Why does the video generation work the way it does?
* Why do birds suddenly appe-... nevermind.
We also would greatly benefit from peer-reviewed tutorial content. Especially for the really difficult stuff.
Epilogue (or, this post is way too long already)...
I don't have any answers to this problem right now, but I want to help preserve this information and I need your help.
In another thread just now:
David Betz wrote:It's amazing that there is no official source for this information. Every time someone wants to understand a Spin binary file we go through the same archeology trying to find ancient sources for this information.
This is true, we are wasting energy having to recover old files that are simply not backed up anywhere. What a silly situation.
Thank you for your time.
Comments
I believe you have discovered a dilemna.
'A dilemma is a choice between two undesirable options. :
Do you move on to the new supported devices or
keep using the older ones.
Preserving older documentation is like catching newspapers in a windstorm.
That's a decision everybody has to make for themselves.
I'm also a fan of 'forcing the zen into things' but it can be taken too far.
It seems like the system is not working that's all.
Some time ago, I asked the same question and a coupla guys pointed out methods of increasing this performance but these were never mentioned this time:
http://forums.parallax.com/discussion/164171/what-is-the-maximum-possible-throughput-of-spi-on-the-prop#latest
It's really time Parallax stepped in and took over this.
Ken, are you ether???
I agree with Dave Hein, Parallax have no obligation to do any more documentation on the P1 system. I think it is entirely reasonable for the community to take up the task of properly fleshing out the details of the more obscure areas of the system.
A wiki type system is good for static reference, which will be required. And, if used sensibly, supports peer-reviewing and discussion (the "talk" pages for each topic allow idea sharing and refinement of the articles themselves). The only thing I don't like about wiki style systems is that they don't really do much to prevent duplication of information or conflicts. A wiki would need to be carefully curated.
A system I really like for small focused tutorials is the Stack Exchange model. For extremely esoteric technical questions in a tight domain, Stack Exchange is unbeatable for simply getting good answers very very fast. Sadly there isn't a single topic on any of the Stack Exchanges that has any worthwhile Propeller related material. It is not entirely beyond the realm of possibility that we might be able to setup a Propeller based Stack Exchange "Beta" domain, but we'd need to get a decent number of people to vote for it.
I will look into this tomorrow, though I think it's probably not got much mileage.
EDIT: I've asked a meta-meta question of the viability of making a beta stack exchange based on the Propeller...
https://area51.meta.stackexchange.com/questions/26949/would-it-be-appropriate-to-create-a-proposal-for-a-narrowly-defined-technology
Case in point, basic electricity and mechanics I learned well as a young student, are "rediscovered" and "invented" as new, when in fact the same knowledge / processes have been around for decades, if not longer. FYI the stuff I learned in grade school & high school, is the new "Maker" engineering community - sloppily made and no craftsmanship whatsoever. Yes, I'm harsh!
Gathering data can be a challenge without collaboration as was proven when I tried to make a matrix of available Propeller boards a few years ago. Just a list of Prop boards, but even though I thought I had an extensive list, once I posted the matrix, others chimed in with tons more.
StackExchange has a system for private corporate use.
https://meta.stackexchange.com/a/197549
If the community can up-vote the best tutorials, questions and answers then the maintenance problem goes away. If people reading this are skeptical of the ability of SE to provide high-quality, targetted answers in a narrow field, have a look on https://electronics.stackexchange.com or https://unix.stackexchange.com/ and look at some of the higher scoring answers. Everyone gets rewarded when good quality content is submitted, reputations are built on consistently good submissions.
Just thinking aloud here but what if Parallax were to obtain its own StackExchange instead of having this forum? I do realise that forums are free to operate (meh, more or less), and this SE system would no doubt be an annual subscription for Parallax (crowd-fund it perhaps?). But the result would be a terrific resource for users of all skill levels.
WHEW! That was hard. I tried setting up Scoold and it didn't go well. I gave up and switched to AllAnswered... MUCH better. It was free and easy and I don't even have to host it! Took about 5 minutes to find the site, login, create the Parallax community, and come back here to post. So, here we are!
https://www.allanswered.com/community/s/parallax/
Someone go answer my question. I really need to know!
Thanks for adding me to the admins. I think the free version of AA is pretty basic. It looks and smells like SE but lacks the features that makes SE actually work in a self-policing way.
And it keeps logging me out all the time, have you noticed that?
Would e.g. PropForth need an own Q&A community or is non Parallax software on topic in the Parallax community?
Is Parallax-Meta for discussing stuff about the Parallax Q&A (like StackExchange splits "topic" and "organisational stuff") a good idea?
From what I can tell, there is zero safety. The interface is very sketchy and has an alarming amount of bugs. It's worse than these Propeller forums in that respect.
Depends... if we were to adopt a good Stack Exchange style model then PropForth would be off-topic because of SE's (very sensible) strictness guidelines. Also off-topic would be: bst, SimpleIDE, PushProp, and likely anything to do with the verilog implementations of the Prop and or unofficial simulation systems. However I reckon that PropGCC questions would be on-topic since that has official Parallax support (or does it?).
It seems that AA does not have a Meta area. Meta is very important on Stack Exchange because it gives users access to ask freeform questions about how to write good Questions.
I'd love to have a REAL Stack Exchange site devoted to Propeller. It is technically possible but we'd need to organise the community we have here to get off their backsides and show support for it. From what I've seen, that is not going to happen, alas.
I know, it seems to be an intractable problem. A while ago I posted on SE's "Area51" Meta about the entry requirements for a new Propeller SE proposal and the requirements seem to be well above and beyond what we are capable of mustering.
A link to my Area-51 Meta question...
https://area51.meta.stackexchange.com/questions/26949/would-it-be-appropriate-to-create-a-proposal-for-a-narrowly-defined-technology
Also, this makes for depressing reading...
https://area51.meta.stackexchange.com/questions/20966/minimum-activity-requirements-for-area-51
I understand that some older stuff has gone away, and that is unfortunate. As far as documenting the details of how the Prop works, and how Spin works it seems like a single living document or a Wiki is that way to go. If somebody could set this up I'm sure that several of us would be happy to contribute to it.
And nearly noone here seems to want a wiki.
The old propeller-wiki on Wikispaces died ages ago and someone rescued it and adapted the pages (still much to do) for living in a GitHub wiki but noone seems to even take notice of it.
No. Stack Exchange is not a place for freeform "discussion". Stack Exchange is a Q&A resource.
This is an important point. SE is NOT a forum. It should not be treated as a forum.
The existing Propeller forum will continue as a valuable resource.