Suggestion: wiki.prjc.com for User Contributed Documentation / Wisdom?

W

wwg

Well-known member
Hey Paul, you seem like a very busy guy here. My cable arrived from you today (thanks very much) and I've finally had time to play a bit with the Teensy-3.1.

After the usual blinky test, I then immediately wanted to try out the usb serial library support, since this is a convenient way to get debugging feedback from the arm side. Documentation that exists for that, seems to be out of date WRT the Teensy-3.1. For example, the documentation suggests that you should call usb_init(). Well... after an hour+ of trying to figure out why my example usb serial program wouldn't work (I was getting "Resource Busy" on the Mac OSX /dev/cu.usbmodem-XXXXX side), I discovered that if I left out the usb_init() call, things suddenly worked. Hmmmm... it turns out this now happens as part of the Teensy initialization (from the ResetHandler -> _init_Teensyduino_internal_). Yet the documentation I saw, suggested this was necessary.

I don't want to pick on the documentation, but rather suggest perhaps that a wiki.prjc.com might help in documentation maintenance/contributions. This is always a struggle as software and hardware goes through continual change. However, if members were able to contribute wiki-style, this may help the community at large. I am willing to contribute, as I am sure, many others would also (judging by their own contributions).

Thanks, Warren
 
+1 for the wiki idea, but my experience with small community wikis is that they tend to accumulate duplicate and inconsistent or outdated information.

I would like to see proper source code highlighting and math typesetting (like MathJax), that would be awesome.
 
Last edited:
I have no experience with that one, but it seems to have a pretty face.

github.com also supports a wiki, but I'm not fond of that implementation (it seems broadly lacking and only suitable as a last resort). I have used dokuwiki (https://www.dokuwiki.org/dokuwiki), which when combined with a google latex feature, let's you do proper (latex) electronics formulas etc.
 
the nice thing about mdwiki is that it can be hosted on githubpages. It's basically just pure markdown files.
 
I'd like to see Paul weigh in before I contribute. The idea is to have an agreed upon collaboration tool and site. I'm not sure we have the general consensus yet.
 
sorry, I don't find that simple enough. My bad. I don't have much time/patience - it has to be immediately obvious. Click, type, post.

The challenge we have is a super simple way to keep things sorted by topic or keywords.
 
I don't want to force anyone... Try it, if you don't like it then feel free to implement another system. If someone comes up with a better system that everybody likes I'll just delete that one. What's for sure is I think we should take the weight off Paul's shoulders by managing it ourselves.
 
stevech: on github it's a matter of clicking edit, doing your modification and clicking save. It hardly gets easier than that. But if you guys want another system, as I said, just do it and I'll delete mine.
 
I'm taking this as a chance to get used to github and that wiki. The learning curve is not too steep so far, and I can edit the pages in my local clone. If Paul doesn't agree, I've learned a lot anyway.
 
The link posted above takes us to
If you want to contribute to this wiki, you can either fork it and send pull requests or I can add you as a commiter.
Click to expand...
Now, erase your brain of all git stuff you know, put on your know-nothing hat, and read the instruction above and begin to ponder.
 
You do not need to know git to use github. There's a big edit button and web based wysisyg editor. But I'm not here to start a platform war. My proposition is up there, do what you want with it.
 
Well, Paul is active in the forum and didn't say anything yet, so I figure that he's not rejecting a wiki categorically and is at least thinking about the options.
 
I can attest to the fact that Paul is *very* busy right now getting ready for Makers Faire coming up in less than 3 weeks. This idea will be addressed, but it may have to wait a few weeks.
 
You must log in or register to reply here.
Back
Top