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

Solving The Documentation Problem - Opinions Please

2»

Comments

  • OK, I took a look at Stack Exchange, and it doesn't seem like a very good platform for compiling documentation. It does seem to be good for Q&A since that's what it's designed for. A wiki or a shared document, or even a webpage full of links would probably be a better way to document the internals of the Prop and Spin. I also looked at the wiki on GitHub. I never knew that it existed. Maybe if it were discussed more on the forum there would be more interest.

    Creating the encyclopedia of the Prop isn't an easy task. There's little motivation for the people that know the information to be involved. It's a lot of work with little reward. The people that are motivated right now are the people that want the information, but don't know where to find it. The information can be found -- it just takes a bit of work. And once they find what they want they'll lose interest in the encyclopedia also.

    I would suggest just creating a new thread with links to other threads and resources that contain the information you want. Put all this in the first post in the thread, or have the first post link to subsequent posts that handle each major subject. It will be tricky keeping all the links up to date, but it can be done.
  • yetiyeti Posts: 818
    edited 2017-07-01 21:11
    Dave Hein wrote: »
    I would suggest just creating a new thread with links to other threads and resources that contain the information you want. Put all this in the first post in the thread, or have the first post link to subsequent posts that handle each major subject. It will be tricky keeping all the links up to date, but it can be done.
    I contradict.

    What if the thread starter leaves? Who will be able to update his summaries? We already have enough examples of orphaned threads and totally out of date information kind of frozen in time.
  • Create a user ID and share the login information privately with trusted volunteers that are interested in maintaining the thread. Problem solved.
  • Dave Hein wrote: »
    Create a user ID and share the login information privately with trusted volunteers that are interested in maintaining the thread. Problem solved.
    That's a hack and abuse of accounts. Parallax probably will not like it.

    Maybe we should take a look at Gollum...

    It uses GIT as storage backend and then distributed and local use of e.g. GitHub (I hope it works with GitLab too) stored wikis is possible.

    I'm just looking for a nice summary about it...
  • Heater.Heater. Posts: 21,230
    What we need here is an archaeologist, a curator, a librarian. Somebody who can find all that old stuff and organize it and preserve it.

    As far as I can tell many Propeller pioneers have moved on, they have no time to revisit the past.

    A classic case is Cliff Biffle who wrote a PASM assembler back in the day. Which was the the one thing that stopped me overlooking the Propeller in the bad old days of the Windows only Propeller Tool.

    Where to preserve such things? I have no idea.





  • It may be a hack, but it would work. I'm not sure if it violates the forum policy. Ask one of the moderators. If it does violate policy maybe they'll give you permission. You would just have to make it clear that that the account yeti_wossname_... is operated by multiple people consisting of yeti, wossname, etc. This should work fine until one of you gets mad and changes the password locking out the other people. :)
  • yetiyeti Posts: 818
    edited 2017-07-01 21:49
    This forum (or forum style software) is (part of) the problem and not its solution. Noone reads threads of 1000 messages. A way to concentrate the information is needed.

    SE can do this, wikis can do this.

    What we need has to be at least a bit wiki like...
  • jmgjmg Posts: 15,140
    yeti wrote: »
    This forum is (part of) the problem and not its solution.

    What we need has to be at least a bit wiki like...

    These seem to be many 'problems' put forward here, just above is the issue of old/legacy/abandonware code ?

    Others want to create a new Q&A area, but that seems to add to the problems, rather than solve anything ?

    A strict focus on Documentation makes sense, but if you really want stability & long life, that probably needs to be a Parallax Web hosted area.
  • Dave HeinDave Hein Posts: 6,347
    edited 2017-07-01 23:10
    yeti wrote: »
    This forum (or forum style software) is (part of) the problem and not its solution. Noone reads threads of 1000 messages. A way to concentrate the information is needed.

    SE can do this, wikis can do this.

    What we need has to be at least a bit wiki like...
    That's why I proposed a wiki-like solution that lives in a thread. The first post is the main screen of the "wiki". I don't think there is a limit on the size of a post, so it could be very long or it could be short. It would link to other "wiki" pages/posts in the same thread. There would also be links to other threads and outside sites. I can understand if you are resistant to this idea, but personally I think the other methods would be less successful. I suggest trying it within the forum first, and if that doesn't work move it to some other site.
  • rosco_pcrosco_pc Posts: 449
    edited 2017-07-04 13:27
    yeti wrote: »
    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.

    Potatohead did the extraction from wikispaces, I put it up on github: https://github.com/rosco-pc/propeller-wiki (with minimal changes to make most work).
    It got announced a few times, but as @Yeti mentioned not many seems to have paid attention ( I got swamped with work and lost interest)

    Anybody with a github account can make changes as far as I know (@cbmeeks did once)

  • rosco_pcrosco_pc Posts: 449
    edited 2017-07-05 00:03
    Had some time today and fixed up the local links. Now it is time to fix external links (lot will require the way back machine and links to the forum require some google-fu).

    See that @yeti and @DavidZemon have started to make chnages :cool:
Sign In or Register to comment.