Documentation Suggestion

[Andy]

I've noticed quite a few comments that have pointed out that it is quite difficult to navigate and find the correct technical documentation via the PDFs on the website.

I think ARM have a good solution to this: http://infocenter.arm.com/help/index.jsp

Web based documentation would be quicker to navigate & search and could be updated more easily. Does anyone else have any other suggestions for improvement?

[jonathan]

As an extension to that idea, I would love to be able to create "virtual documentation" or tutorials by simply referencing sections from existing documents which can get pulled in to create new tutorials.

[begin tutorial]

This is a new tutorial teaching you how to flash an LED on the XC-1A using assembler.

[insert ref{xc1a/installation}]

Once you have installed your XC-1A, you need to install the XMOS tools.

[insert ref{tools/installation}]

Then read the assembler manual, in particular the bits on ports.

[insert ref{xc/appendix/including_assembler/ports}]

Now you need to work out how to use the tools with the assembler so you can program the board.

[insert ref{tools/assembler}]

As a reference:

[insert ref{architecture/assembler}]

Now, the program you need is:

Etc.

[end]

Or perhaps that's stupid.

[lilltroll]

I like the documentation idea. Most of my questions are answered somewhere in all the pdf - but I never kow where to look whithout asking here first.

Since I cannot relate which "field"/chatper the questing belongs to - I do not know where to search in the pdf-manuals. I would like more examples as well. I have a hard time to read the grammar, like:
fnop fnip {[%&34, &7];#reg()^.~!0["lpc"]} - it is :?: :?:

Some small code examples would help out.

[Folknology]

Html documentation will always win over PDF documentation because it can be broken up and searched over the web.

Perhaps a wiki would be even better allowing the community to add and improve documentation.

*Update I'm sure Drupal has a wiki plug in, it would be trivial to add, Jason?

regards
Al

[jason]

The wiki stuff is certainly on my to-do list.

I will get back to you with regards this.

It appears there may be some integration possibilities with mediawiki although it appears to be a non supported module i.e. here is how someone has managed to do it with specific versions of drupal/media wiki, use at your own risk. So I need to analyse it a bit more and see if there is a more elegant solution. Also will check for security issues etc.

[jason]

Update: With regards wiki I have successfully performed a basic integration with a wiki on my dev server allowing for shared auth with Drupal.

Still needs a bit more work, but needless to say, I am working on it and it is looking promising! I will keep you guys updated so you know when to get excited :-)

[TonyD]

Update: With regards wiki I have successfully performed a basic integration with a wiki on my dev server allowing for shared auth with Drupal....

That's good news Jason.

[BrianMiller]

I like the wiki idea. I run dokuwiki on a dev box and have been stuffing notes about various things I've run across in the pile of manuals found on xmos.com/documentation . It takes a little bit of effort to compile a list of commonly needed reference pointers, but without doing some of that housekeeping I'd waste a lot of time re-reading piles of stuff all the time.

[jason]

Yes we will need to keep this as orderly as possible or else it could very easily degrade into a giant mind dump all over the place. Key topics/faqs or such should be easy to get to especially as a new user may find it overwhelming anyway. So who else has run a sizeable wiki before?

[Andy]

I've run a wiki before - I found it was key to have a good index page with well organised sections, otherwise content tends to get lost quite easily.