Documentation Suggestion

Archived group discussions. Please post all group discussions under their relevant XCore group page.
User avatar
Andy
Respected Member
Posts: 279
Joined: Fri Dec 11, 2009 1:34 pm

Documentation Suggestion

Post by 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?
User avatar
jonathan
Respected Member
Posts: 377
Joined: Thu Dec 10, 2009 6:07 pm

Post by 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.
Image
User avatar
lilltroll
XCore Expert
Posts: 956
Joined: Fri Dec 11, 2009 3:53 am
Location: Sweden, Eskilstuna

Post by 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.
Probably not the most confused programmer anymore on the XCORE forum.
User avatar
Folknology
XCore Legend
Posts: 1274
Joined: Thu Dec 10, 2009 10:20 pm

Post by 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
User avatar
jason
XCore Expert
Posts: 577
Joined: Tue Sep 08, 2009 5:15 pm

Post by 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.
User avatar
jason
XCore Expert
Posts: 577
Joined: Tue Sep 08, 2009 5:15 pm

Post by 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 :-)
User avatar
TonyD
XCore Addict
Posts: 234
Joined: Thu Dec 10, 2009 11:11 pm
Location: Newcastle, UK

Post by TonyD »

jason wrote: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.
User avatar
BrianMiller
Active Member
Posts: 33
Joined: Wed Jan 13, 2010 7:50 am
Location: USA, NC, Raleigh

Post by 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.
User avatar
jason
XCore Expert
Posts: 577
Joined: Tue Sep 08, 2009 5:15 pm

Post by 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?
User avatar
Andy
Respected Member
Posts: 279
Joined: Fri Dec 11, 2009 1:34 pm

Post by 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.