There is a community wiki on Xcore:
https://www.xcore.com/wiki
Open Source Documentation
-
- Experienced Member
- Posts: 104
- Joined: Fri Dec 11, 2009 8:29 pm
-
- Respected Member
- Posts: 377
- Joined: Thu Dec 10, 2009 6:07 pm
If XMOS documentation (e.g. manuals, datasheets, etc) were to find its way into the Wiki, would XMOS - or the copyright holders - consider that copyright infringement?
-
- Experienced Member
- Posts: 104
- Joined: Fri Dec 11, 2009 8:29 pm
Good question. I don't know the answer but can find out. I expect it would be OK providing that any alterations were clearly marked as not originating from XMOS but I'm just speculating.jonathan wrote:If XMOS documentation (e.g. manuals, datasheets, etc) were to find its way into the Wiki, would XMOS - or the copyright holders - consider that copyright infringement?
-
- XCore Addict
- Posts: 216
- Joined: Wed Feb 10, 2010 10:26 am
For all this reasons it would be best if XMOS puts it there ;)davelacey wrote:Good question. I don't know the answer but can find out. I expect it would be OK providing that any alterations were clearly marked as not originating from XMOS but I'm just speculating.jonathan wrote:If XMOS documentation (e.g. manuals, datasheets, etc) were to find its way into the Wiki, would XMOS - or the copyright holders - consider that copyright infringement?
-
- Respected Member
- Posts: 377
- Joined: Thu Dec 10, 2009 6:07 pm
Agreed. The ideal thing would be to have the source + build system on github. The idea that the community will produce somehow worse documentation than XMOS is a bit of a fallacy as the documentation contains so many errors as it is, it can only get better...Interactive_Matter wrote:For all this reasons it would be best if XMOS puts it there ;)
Best thing in my view would be: open-source documentation, with curated "stable docs" pulled occasionally from the repository for use on XMOS website. XMOS and community edits made to repo.
This idea is not new - but perhaps the view inside XMOS has changed to enable this to happen?
-
- XCore Legend
- Posts: 1274
- Joined: Thu Dec 10, 2009 10:20 pm
I Agree placing the source docs on github/Xcore would be the best way forward, and would speed things up - many eyes etc..
restructuredtext would be a good format to do it in by the way.
regards
Al
restructuredtext would be a good format to do it in by the way.
regards
Al
-
- XCore Addict
- Posts: 216
- Joined: Wed Feb 10, 2010 10:26 am
Good idea. But I got a Wiki myself (edited by contributors, not me) and my experience is that the barrier to enhance the documentation must be as low as possible. If it is more than two clicks to update a text you loose 90% of potential contributors. And less than 10% dare to do those two clicks anyway.Folknology wrote:I Agree placing the source docs on github/Xcore would be the best way forward, and would speed things up - many eyes etc..
restructuredtext would be a good format to do it in by the way.
regards
Al
With some human check (recaptcha/catpcha or similar) vandalism is a mild problem - from my experience.
-
- Junior Member
- Posts: 6
- Joined: Thu May 27, 2010 10:13 am
Many people contributing to a single document is essentially a wiki, and as such whether its quality gets naturally better or worse over time is debatable. However, we do put a fair amount of effort into authoring product manuals and datasheets: to ensure accuracy, present consistent narratives and align messaging with company marketing objectives. Product manuals also imply a set of features that we officially support. In the case of datasheets, many customers consider this contractual (despite the No Warranty boilerplate). In my opinion it's therefore important that XMOS retain the content rights to many of these documents. That said, where errors are reported to us by the community, we should of course publish corrections without undue delay.jonathan wrote: If XMOS documentation (e.g. manuals, datasheets, etc) were to find its way into the Wiki, would XMOS - or the copyright holders - consider that copyright infringement?Agreed. The ideal thing would be to have the source + build system on github. The idea that the community will produce somehow worse documentation than XMOS is a bit of a fallacy as the documentation contains so many errors as it is, it can only get better...Interactive_Matter wrote:For all this reasons it would be best if XMOS puts it there ;)
We've recently open sourced a 'tips and tricks' guide which may be of interest and has the potential to evolve into a comprehensive programming guide for both XC and the XCore architecture.Interactive_Matter wrote: @XMOS can't you just create wiki pages for all the documentation & hints you got in your PDFs an on github. Then we can discuss edit, reorganize, link and rework it there. Documentation should be a living entity!
-
- Respected Member
- Posts: 377
- Joined: Thu Dec 10, 2009 6:07 pm
There is nothing in the creation of a publicly-editable resource that prevents XMOS from creating authoritative copies, spun out of this resource and curated as required. The effort required on XMOS' part is probably roughly the same (or less) but the quality of published "living" documentation will be higher.
My interpretative summary of the above is: if you want Wiki docs, write your own.
That's perhaps not the best way to look at it.
There are countless errors in the documentation. The second I have to go through the ticketing system to report an error and then wait 2 months before version 18.3.4.1b) of the relevant document contains the correction (for example, deletion of an extra "the", or a typo) I can't be bothered. Same goes for the numerous errors on port tables etc that existed in earlier versions of the docs. If I could click "edit" and fix the errors, I'd bother to make the effort as and when I spotted errors...
And you'd have better docs.
My interpretative summary of the above is: if you want Wiki docs, write your own.
That's perhaps not the best way to look at it.
There are countless errors in the documentation. The second I have to go through the ticketing system to report an error and then wait 2 months before version 18.3.4.1b) of the relevant document contains the correction (for example, deletion of an extra "the", or a typo) I can't be bothered. Same goes for the numerous errors on port tables etc that existed in earlier versions of the docs. If I could click "edit" and fix the errors, I'd bother to make the effort as and when I spotted errors...
And you'd have better docs.
-
- XCore Legend
- Posts: 1274
- Joined: Thu Dec 10, 2009 10:20 pm
I'm really not interested in the messaging and marketing objectives inside operating documentation, I'm interested in the facts and the information that help me get the job done. I think you need to separate glossy corporate briefs, brochures and white papers from the factual documents enumerating architecture, operation and implementation. These documents need to be optimised for reference not presentation or market positioning, they are functional, working efforts, that can be improved by those whom they are aimed toward. Any organisation that thinks it knows better than its community, customers and peers is destined to make the same mistakes over and over. Why turn away assistance from those that care most passionately about it....However, we do put a fair amount of effort into authoring product manuals and datasheets: to ensure accuracy, present consistent narratives and align messaging with company marketing objectives..
just my $0.50
regards
Al
Last edited by Folknology on Fri Mar 25, 2011 10:23 pm, edited 1 time in total.