Open Source Documentation

[davelacey]

There is a community wiki on Xcore:

https://www.xcore.com/wiki

[jonathan]

There is a community wiki on Xcore:

https://www.xcore.com/wiki

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?

[davelacey]

There is a community wiki on Xcore:

https://www.xcore.com/wiki

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?

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.

[Interactive_Matter]

There is a community wiki on Xcore:

https://www.xcore.com/wiki

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?

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.

For all this reasons it would be best if XMOS puts it there ;)

[jonathan]

For all this reasons it would be best if XMOS puts it there ;)

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

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?

[Folknology]

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

[Interactive_Matter]

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

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.
With some human check (recaptcha/catpcha or similar) vandalism is a mild problem - from my experience.

[dougxmos]

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?

For all this reasons it would be best if XMOS puts it there ;)

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

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.

@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!

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.

[jonathan]

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.

[Folknology]

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

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

just my $0.50
regards
Al