PJRC and Teensy(s) need a Wiki

@Pedvide: last thing on my mind, about this, is money atm - to try to pre-consider as carefully as I can manage to give it time right this second I can't see myself ever asking for more than a dollar, and seriously; not going to happen for quite some time, pretty sure.

Thanks very much Pedvide, you, defragster and duff I am counting now as founding members of the wiki - maybe I could have held out for five after all (if they turn up quick enough :D)

@others: If you have posted a message in this thread that you feel should have indicated me to count you 'in' then please alert me, I can be a bit blindish (ignorant even, perhaps) at times - I sure don't mean offense.

If you haven't posted anything that I could reasonably imagine means I should count you in and you want to be counted in you've got to be getting a clue what to do by now.
 
Pedvide said:
I restate my interest in the wiki thing.
Click to expand...
Awesome. I see you now Doxygen'ate your ADC code : https://github.com/pedvide/ADC/tree/master/doxygen! Since it starts with "A" it was one of two I tested on 4/14 when it didn't show (rob this will likely be a better config than what I sent).
Your Forum post now stretches 7 pages! going back 14 months. Great code and good example of how 171 messages make finding a key fact tough . . . where a single up to date wiki page should just show what you need to know without a series of posts tracking evolution and bugs now fixed.

Has anyone seen well formatted wiki examples?

http://xbee.wikispaces.com/Arduino+Set+up
http://kalshagar.wikispaces.com/
http://arduino-info.wikispaces.com/ [ouch - ick.]

NXP%27s+LPC11XX+Cortex-M0+ARM+Microcontrollers
$1-$2/month per user! Runs on: https://www.atlassian.com/software/confluence

Arduino.cc might be a common presentation style - but not editable and not how I saw TOC and needed content showing up
>> Reference Language | Libraries | Comparison | Changes
http://playground.arduino.cc/
 
I try to update the 1st post with all useful information, that post would be the foundation for the wiki's ADC entry.
 
Pedvide said:
I try to update the 1st post with all useful information, that post would be the foundation for the wiki's ADC entry.
Click to expand...

Good plan - I was doing a for instance - not saying it was out of sync - your intro page is good. But I never know reading these things, and like facebook you can loose a lot of time reading threads.
 
I will try to speed you to a position of being able to make that wiki entry, Pedvide. Mustn't rush it too hardcore tho.

[PLAIN]http://www.mediawiki.org/wiki/Extension:DoxyWiki[/PLAIN] looks potentially cool as - I am yet to attack my server, I've got to do it in a simile VM first; might have something to show founders by tomorrow night but, chances are....

I'm probably going to end up having to give duff (or one (or more!) of those guys) root access to my VM before even hitting the VPS :p
 
I tend to think that things that read the source to look for markers to bring out for documentation (as I understand Doxygen might be used for) work great in some projects, such as a monolithic project that has incorporated its use from the beginning. However, it likely will not work as well in open source projects like Arduino/Teensy where a bunch of libraries written by a bunch of different people over time, including people who contribute a library and then move on to other things and never touch the library again.

In my experience, such things are useful if you want to know how to call a function, but it doesn't give you a higher level idea of how the module fits in the universe, tradeoffs between other ways of doing things, and how to get started, including examples.
 
First, please let me apologize for my recent silence, over the last 2 days this thread has grown to 56 messages! As you can see from the message history, I fell behind on answering questions over the last several (my email inbox is still FAR behind). I've been catching up over the last day or so. I tried to prioritize answering specific tech questions first. I believe I'm now caught up to everything, at least for the moment, so now let's talk of wikis and community documentation stuff.

TL;DR = I like the idea of trying a Wiki, but I'm skeptical about Doxygen.

Lets talk of wiki software to get started.

I must confess, while I've read lots of wikis and edited a few pages, I know relatively little about which wiki software offers what features.

I do know I'd like to see at least 3 things:

1: This should be wiki.pjrc.com, either running on the same server as the forum, or PJRC will buy another dedicated server if it places too much load on the forum server. The forum server use a pretty standard LAMP setup, which I'm guessing will run almost any wiki... but obviously something requiring Windows, IIS and MSSQL would be out of the question!

2: Ideally, the wiki should integrate with vbulletin, so user accounts are shared between the forum and wiki.

3: Editing pages should be fairly easy. Hopefully arcane markdown syntax won't be a requirement. Adding and updating images should be straightforward (at least no worse than vbulletin's somewhat convoluted image attach), not involving a complex process to first establish each image as its own wiki asset.

Maybe other issues are important about the software? At this beginning point, I'd really like to talk of the selecting the particular wiki software. That needs to happen first.

Later, issues about the information architecture, content, access policy and other stuff will need to be discussed. There's already a lot of that in this thread. It's all good stuff to think about, but kind of a moot point if we don't first get some decent software up and running.

I do appreciate the offers to set up a 3rd party server. But I think this really should have a solid start on wiki.pjrc.com (so links don't ever break), with vbulletin integration. So let's discuss wiki software options to get this started!
 
Maybe I ought to explain my Doxygen viewpoint? Actually, I think Doxygen or something like it will be great, in a distant but wonderous future when Arduino gains autocomplete and context-sensitive documentation. Doxygen is great for making highly detailed reference manuals. I firmly believe (almost) nobody really reads comprehensive and lengthy manuals, but people do use and really appreciate context-aware appearance of detailed info.

Every Doxygen website I've seen looks like a lot of trees that obstruct the view of their forest. I know, in theory, it doesn't have to be that way. Better comments could be put into the code, theoretically making anything appear as the final output. But the strong tendency is for Doxygen created websites to mirror the source code structure and document the minutia of each function and its parameters.

I'm willing to reconsider Doxygen, probably much later. For now, with let's give a wiki approach a try.
 
We use dokuwiki at our company for (internal) documentation. It's:
  • FOSS
  • Runs on LAMP
  • Easy setup (not even a db required)
  • Pretty simple syntax
  • All other typical wiki features
Apparently it also has a vBulletin plugin so you can use the same authentication.
 
Paul, I completely understand your preference to host and I simply hope it doesn't chew away your time - I imagine the others should be thrilled and don't mind that I am not going to set about hosting anything in competition with you.

I am reasonably certain mediawiki is amongst best candidates, I've previously mentioned to you that it has integration for vBulletin.

Happy to help; if you would like me to try actually integrating vBulletin 4.2.2 and some allegedly integrable wiki software - I don't mean your copies, access to pjrc servers at all; VM will do, as I am sure you will probably do it all in yourself.
 
Any idea where I should look for mediawiki's vbulletin integration? I found several pages, for abandoned plugins that only worked with older versions of vbulletin.

And yes, I also hope it won't chew up too much time, but this really is pretty important and worth putting at least some time into (and away from debug and/or a high-end Teensy development).
 
Hmmm, see what you mean about lack of recent development by looks - I am going to bed but tomorrow, if you haven't specifically signalled me not to, I will grab a copy of vBulletin 4.2.2, set up some dummy users in a VM install and then see how what fails about the most recent integration extension I can find; while since I was knee deep in PHP but I may quickly gel and make it go.

If I make it go I can either send you as detailed a description of what I did to achieve that or just send a copy of the source of the extension modified appropriately - either way, if this makes it that far, it should be tested as thoroughly as possible to make sure it isn't any more susceptible to hacking than before I began.

If it becomes a 'healthy' wiki the amount of time you need put towards it should taper off imho.
 
I've had good results with mediaWiki also it also has Latex pluggin for nice math formulas, could be useful for the Audio library but I did see vaultWiki which is paid service buts looks like it intergrates with vBulletin out of the box.
 
Looks like vaultWiki is $10/month. Supposedly yearly and lifetime subscriptions also available, but I did not see prices listed for those options.
 
Dokuwiki is what is used in my first example that made it seem like a good idea: http://digistump.com/wiki/, tied to the forum would be great

<edit>: I made some edits on this one and adding images might be cleaner than I found but it wasn't setup to be as nice as forum.pjrc.
 
Last edited:
PaulStoffregen said:
... context-aware appearance of detailed info.
Every Doxygen website I've seen looks like a lot of trees ...
mirror the source code structure and document the minutia of each function and its parameters.
I'm willing to reconsider Doxygen, probably much later. For now, with let's give a wiki approach a try.
Click to expand...

wiki.PJRC.com support sounds awesome! If a wiki entry links each library to the github that would allow source view outside the IDE.

For Doxygen - your notes are all true - and good - generally positives when a mirror to the code is what many would want. A hand holding context appearance is handy for those that haven't seen the same or similar code 10 or 1,000 times - or much code at all and don't have 'grep_foo' or an editor other than Arduino IDE.

A minimal start to Doxygen just takes one up front paragraph in each library, and a script to compile the HTML. Even without adding comments you see each function and its params and tedious buried detail in a better browser interface than github. Given that it pulls the same data out that the compiler sees - the technical part is accurate and repetitively complete in various trees - and bottoms out at a text view of the source without going GitHub or local editor.

RadioHead example allows you to dig into the same tree of info in varied ways for a complex overloaded interface to networking - it even shows the associated PDE's and gives click access to review the source faster and easier than a crummy IDE window:
http://www.airspayce.com/mikem/arduino/RadioHead/examples.html

Perhaps if a trial on ADC were set-up to expose it others could follow.

<edit> I pulled github.ADC and like Radiohead it only shows the .h files in file view
 
Last edited:
Some of you may have already seen this exemplary web site for RadioHead - doxygen created arduino/Teensy hardware targets.
doxygen mainpage yields the introductory page and navigation.
And embedded doxygen in all code in all files yields the rest of the document.

Example:
http://www.airspayce.com/mikem/arduino/RadioHead/

This is self-documenting code - meaning there are simple/brief doxygen notations for all key functions and variables, and structured notes left for code that's hard to decipher or for the author to REMEMBER after a year!

there are lots of similar sites on the 'web. Editing the source and running doxygen now and then to update the web site is a low-work situation. There is one-time work to write the mainpage. Then discipline needed to annotate the source and keep doing so.
http://www.stack.nl/~dimitri/doxygen/results.html
 
Last edited:
We used DokuWiki internally within my work group for about 5 years. We have not used it for a couple of years now, due to various internal corporate changes. I also hosted a MediaWiki site for an Eve Online guild for a few years.

DokuWiki was very easy to set up and easy to use. It didn't have all the bells and whistles of MediaWiki, but it did the job pretty well.
 
A wiki would mean much more work for Paul.
Because the website is needed too, the amount of work to keep everything up to date (and to review changes in the wiki + moderations) would be doubled. The third thing is this (great!) forum.
 
The web is very T_3 or T_2 centric - A current Wiki could easily update and replace the content 'hidden' there. All the main hits could pop to the wiki page and the whole world is there.

Indeed the Forum is top notch - but not searchable and also not focused to a general point (except like the first post of ADC)- but the point at hand - as it should be.

Hopefully wiki edit is a per user feature and could be made exclusive with revocation as needed.

As noted I like the user feel of DokuWiki - but I didn't find the clue for easy image posting - but that may be a setup issue.

I posted a question related to a thread - Q: 'how do I XYZ ... I saw it somewhere' A: 'been done more than a few times, not going to repeat now'.

If there was a searchable wiki then I could hope to find the item XYZ myself, and if not the Answer could have been see "wiki.pjrc.../XYZ"

And as noted - if I introduced a twist XYZ..XyyZ then a quick wiki edit would be permanent public update linking to see "wiki.pjrc.../XYZ..XyyZ"
 
VaultWiki looks really interesting, mainly for well supported vbulletin integration. If it's even a little less trouble for me to set up and maintain (Robin may end up doing some), I'm perfectly happy to pay the $150 permanent license fee.

If you guys could look into the vbulletin integration on MediaWiki and DokuWiki, with a critical eye for how well it actually works with vbulletin 4.2.2, that'd really help. The info I was able to find with a little searching seems to suggest old, no-longer-maintained plugins and bridges are needed.
 
robsoles said:
@others: If you have posted a message in this thread that you feel should have indicated me to count you 'in' then please alert me, I can be a bit blindish (ignorant even, perhaps) at times - I sure don't mean offense.

If you haven't posted anything that I could reasonably imagine means I should count you in and you want to be counted in you've got to be getting a clue what to do by now.
Click to expand...

Me me me. Happy to contribute cash also.
 
PaulStoffregen said:
If you guys could look into the vbulletin integration on MediaWiki and DokuWiki, with a critical eye for how well it actually works with vbulletin 4.2.2, that'd really help. The info I was able to find with a little searching seems to suggest old, no-longer-maintained plugins and bridges are needed.
Click to expand...

This is the best vBulletin to mediaWiki plugin I could find: http://vbsso.com, it supports vB 4.2 and mediaWiki version 1.23, the latest mediaWiki looks to be version 1.25. Looks like they have DokuWiki plugin too. The only cost I can see is 49 bucks to remove foot link.

edit: not sure about vBulletin 4.2.2 though, i'll see if I can find out.
 
Last edited:
Finally in a position to start looking at it (long story, dw) and it occurs to suggest:

Maybe there will be less administation (configuration etc) issues if a wiki platform be chosen with no intention to directly integrate with the vBulletin system after all - maybe that vaultwiki thing is the ducks guts but between having 'vault' in the name and being paid just makes this pedantic part of my mind want to flag it.

MediaWiki is looking more and more a worry to me, the latex support seems potentially as dodgy as the vB integration looks.

Against whatever actual level of rigmorole involved in integrating the least difficult one to integrate and then the potential for little gotchas later how hard would it be for standalone wiki to be deployed with an initial policy of only allowing people who match the criteria PJRC used to choose for Teensy LC beta group?


Anyway, I am not going to rush at it but I will go through with the vB + mediawiki experiment I mentioned; I can show it to you, if you like (let you access and poke away at it), without letting it go public by giving you host information rather than making a DNS entry (sub domain of a domain I already control) or putting it in a subfolder of one of the sites I control.
 
I'm looking forward to hearing the results of your vbulletin+mediawiki experiment. Even just some notes about the setup process, what combination of settings actually works, would be incredibly helpful.

Let's not forego the vbulletin integration. In the earlier days, this forum got a little over one spammer or spambot registration per minute, despite the captcha. Spam cleanup was a huge burden for Robin and me. Now we're a much bigger spam target. The last thing I want to do is open up any other registration process.

I'm willing to put some real effort into setup and ongoing high-level wiki editing, but PJRC just can't go back to the days of playing an exhausting game of whack-a-mole with spammers.
 
Last edited:
You must log in or register to reply here.
Back
Top