Shop OBEX P1 Docs P2 Docs Learn Events
Solving The Documentation Problem - Opinions Please — Parallax Forums

Solving The Documentation Problem - Opinions Please

WossnameWossname Posts: 174
edited 2017-06-15 18:32 in Propeller 1
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:
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.
«1

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

  • I'll volunteer server space on my VPS for whatever solution is agreed upon here.
  • I don't know if it makes sense to use git to keep everything together? You could centralize at say github, and then if that goes down someone can host it somewhere else - e.g. gitlab. Just thinking about git since it makes it so easy to clone everything and relocate as needed.
  • I thought about a Knowledge Base, the other day when someone was asking about SPI speeds.

    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
  • Cluso99Cluso99 Posts: 18,066
    Documentation is a frustration we have all had at some point in time. We have all done our bit over the years.

    It's really time Parallax stepped in and took over this.

    Ken, are you ether???
  • I think Parallax has adequately documented Spin and PASM to allow people to program. I don't see that they need to document every detail about how the Spin interpreter is implemented, or what's in a method table or the format of a stack frame. However, we are curious creatures, and we do want to know all the details. Personally, I would like to see a wiki that documents all these details. I if someone could establish a wiki site I think that people from the Prop community could fill in the details in a matter of a few weeks.
  • WossnameWossname Posts: 174
    edited 2017-06-16 20:46
    When Parallax took the generous step to open source the silicon design for the P1 they gave a huge, unprecedented gift to the community. Can you imaging Atmel or Renesas or TI doing that?

    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

  • I belong to several Wiki sites run by the user's groups, and not a happy camper. Many articles are written by people that have little or no knowledge of the topic they are supposedly writing about, it "just sort of works" mentality. It is then taken as absolute knowledge because it is on the Internet, when in fact it is bogus and completely worthless because no one has bothered to school themselves in the basics of the subject they are writing about.
    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!
  • @PropGuy2, if not a wiki, then what would you suggest instead?
  • PropGuy2PropGuy2 Posts: 358
    edited 2017-06-17 22:36
    I think there are already plenty of good examples and code snippets in OBEX and certainly good discussions on this Forum. Using peer review of the more obscure topics would weed out the bad logic & mis-steps in the more technical subjects. A good solid knowledge base would be a start - Authoritative articles, grouped by area of interest or subject. Something more than a "how to" but maybe less than a college text book or lecture. Again, using the best of the best of OBEX and these Forums, and organizing the subjects in a solid Knowledge Base.
  • I agree with others that documentation is needed in the sense that Wossname is requesting. I recall that when I was trying to figure out video settings in standard video drivers from OBEX, it wasn't until I got my hands on the manual for the Hydra that I figured it all out. That book is priceless and much of its content should be readily available through a wiki style source for others. As Wossname mentioned, I bet I have code on my laptop from the old forums that was severed from a thread due to migration or other action and someday, someone will be asking for it. A full blown Propeller Wiki would be the answer, but proper maintenance could be a challenge simply due to different mentalities of the right way to do things on the Propeller.

    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.
  • WossnameWossname Posts: 174
    edited 2017-06-18 10:11
    A full blown Propeller Wiki would be the answer, but proper maintenance could be a challenge simply due to different mentalities of the right way to do things on the Propeller.

    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.

  • Wossname wrote: »
    StackExchange has a system for private corporate use.

    https://meta.stackexchange.com/a/197549
    There are some SE-clones... https://meta.stackexchange.com/questions/2267/stack-exchange-clones ...maybe someone here has already seen some of them in the wild wild web?
  • yeti wrote: »
    Wossname wrote: »
    StackExchange has a system for private corporate use.

    https://meta.stackexchange.com/a/197549
    There are some SE-clones... https://meta.stackexchange.com/questions/2267/stack-exchange-clones ...maybe someone here has already seen some of them in the wild wild web?

    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!
  • Ok, that looks like a good starting point. I'm a bit concerned about the fact that it shows people's emails in plaintext. Can you go into the administrator settings and make sure everything is set sensibly please? ASAP would be highly appreciated :)
  • I've disabled private messaging between users. Looks like the software may not support intern messaging, which is why the emails were public when I had it enabled. I've also added you as a moderator/admin.
  • WossnameWossname Posts: 174
    edited 2017-07-01 14:34
    Hi David,

    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?
  • No, I haven't messed with it much at all, and never used SE as anything more than an occasional user.
  • I'm seeing a lot of bugs in this AA system. Might not be viable. Good job it's free eh?
  • Definitely good thing it's free! We can continue the search for something else then. Scoold looked pretty cool... if you can get the application.conf file figured out (test locally on your own computer), I'll host it on david.zemon.name. I wasn't able to get the "Sign Up" page to work (it was displaying a header with no sign up options).
  • How safe is the collected know how in there? Are there flexible export and backup features?

    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?
  • yeti, all good questions...
    yeti wrote: »
    How safe is the collected know how in there? Are there flexible export and backup features?
    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.
    yeti wrote: »
    Would e.g. PropForth need an own Q&A community or is non Parallax software on topic in the Parallax community?
    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?).
    yeti wrote: »
    Is Parallax-Meta for discussing stuff about the Parallax Q&A (like StackExchange splits "topic" and "organisational stuff") a good idea?
    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.

  • Wossname wrote: »
    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 think I mentioned the idea of having a Propeller-SE site already a few times but there was exactly zero echo... :-/

  • yeti wrote: »
    Wossname wrote: »
    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 think I mentioned the idea of having a Propeller-SE site already a few times but there was exactly zero echo... :-/

    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
  • That doesn't seem hard at all! We already have 4 questions and 5 users on AA. Let's make it happen.
  • DavidZemon wrote: »
    Let's make it happen.
    \o/
  • So what is it you guys are proposing? Moving the Propeller discussion to Area 51 or Stack Exchange, or whatever it is? I don't see the point in doing that since Parallax already has this forum established, and it seems to already serve the purpose for asking questions and getting them answered. The forum can be searched to find previous discussions.

    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.
  • yetiyeti Posts: 818
    edited 2017-07-01 19:28
    Dave Hein wrote: »
    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.
    SE has enough features of a wiki to keep the information alive even if the original writer has gone.

    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.
  • Dave Hein wrote: »
    So what is it you guys are proposing? Moving the Propeller discussion to (...) Stack Exchange

    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.

Sign In or Register to comment.