Open Source Documentation

[xmark]

Hi Folks,

We don't have a problem in principal. Would it be acceptable to create document wikis like the Community repo on github? For non-committers issues would be raised in the usual way.

Cheers,

-Mark

[Interactive_Matter]

....

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

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

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.

I think a documentation wiki does not render datasheets obsolete. You are right datasheets are authorative and define the product properties. I do not think that this can be replaces by a wiki.
But as jonathan put it. If the base for the official documentation is in a wiki it would be easier for XMOS to create the authorative documents (or even more marketing targeted), since you can look up or copy paste (in best case) well edited texts from the wiki.

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

Hi Folks,

We don't have a problem in principal. Would it be acceptable to create document wikis like the Community repo on github? For non-committers issues would be raised in the usual way.

Cheers,

-Mark

My main problem with all your tips & tricks and special documentation is that it is very cluttered - I can download some PDFs for products, then I need to go to the chips pages and download specs there, then I have to find some general how to documents on the web site and scan for tips & tricks in the forum and on github.
In an ideal world I would have anything in one place and if pages are contradictive I can simply copy the contradictive parts in both documents and e.g. as in the forum what is correct and what not.
I think public wikis in github is a good way.
But giving only contributors write access would create a barrier to edit the text which can limit the usability. E.g. I am starting with XMOS currently. So I got quite a good view what is a good introduction and what not and which information needs to be ordered (or linked) in which way to get a good overview. But I am not on the contributor list (since I have created nothing yet to justify adding me to the contributor list - understandable). But If I got to raise issues for the documentation, I perhaps do it and it get's improved perhaps. If I can just edit I copy over some text block, create a link or create a comment directly and perhaps help somebody.
If you e.g. say anybody with an account on XCORE can edit the documents it would massively reduce the barrier. And we have a wiki here too.

But to clarify that: XMOS is allready doing quite a good job beeing open. I try to persuede my company (a web content management company) to do the same and they have the same quality issues (concerns and results ;) ). But the result is that the documentation department still has control over the documentation but the documentation remains errornous and thin in many areas. I do not think it helps anybody.

I own a wiki myself at http://www.beam-wiki.org/wiki/Main_Page - if you got a look at the changes you can see that there is one guy massivley contributing - not in the format I like, but if I would like to change it I could. And there are some people doing minor edits just fixing typos or some words ar add links between pages to improve readability. Despite the fact it is completely open (only protected by a captcha) the vandalism is quite rare (about 3-5 pages per month) and really easy to fix (undo). It takees a lot of courage for the contributors to change structure. They have much respect for the stuff that is already there.

Marcus

[dougxmos]

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.

Apologies if this came across as unhelpful. I'm certainly in favour of XMOS collaborating on documentation, and if the community decides the Wikis are the way to go then no issue with that. But I'm not aware of that many semiconductor companies that maintain "living" versions of their product manuals or datasheets on publicly-editable twikis. So perhaps the issue is simply striking the right balance.

In the case of XC, we've published a small, official guide and language specification, and opened the tips and tricks document for community collaboration. I'd expect the quality of this document to get better and better over time. In the case of the XS1 architecture, the official manual contains a detailed ISA specification and edits should be limited, but there's perhaps a case for a collaborative architecture guide. In the case of datahseets, I still favour a single location where customers can go to find the data, which is known to have gone through a formal authoring and publishing process.

[jonathan]

Apologies if this came across as unhelpful. I'm certainly in favour of XMOS collaborating on documentation, and if the community decides the Wikis are the way to go then no issue with that. But I'm not aware of that many semiconductor companies that maintain "living" versions of their product manuals or datasheets on publicly-editable twikis.

How cool it would be to be breaking new ground rather than retreading old.

In the case of XC, we've published a small, official guide and language specification, and opened the tips and tricks document for community collaboration. I'd expect the quality of this document to get better and better over time. In the case of the XS1 architecture, the official manual contains a detailed ISA specification and edits should be limited, but there's perhaps a case for a collaborative architecture guide. In the case of datahseets, I still favour a single location where customers can go to find the data, which is known to have gone through a formal authoring and publishing process.

I understand what you're saying, but all you have to do is create formal binding datasheets on xmos.com that (e.g.) once-monthly curate any suggestions from a public "living" source. Note: I think the Wiki versions are likely to be more accurate and up-to-date 99.9% of the time than the "curated" XMOS ones.

I don't think there's any issue with making this happen.

Here's an idea:

1) The source of various documents is kept on github, and can only therefore be edited by contributors there (who we assume are pretty much trusted, and where there is complete ease to brand/revert changes etc, with no damage to reference copies)
2) This source is translated periodically into a wiki form, which is publicly-editable, and PDF form, which is posted on xmos.com
3) Periodically (before each source pull to the wiki) these suggested edits are curated by one or more github contributors back into the source on github. Goto 2).

Just a suggestion, but something like this would really help, and there are countless examples of people using far less restrictive processes than this to document commercial products.

[Folknology]

I would definitely go for a Github based solution with contributor agreement protection, this will also remove many of the high maintenance associated with destructive spam issues even using captchas. A simple text format would also make contributions easier.

And Doug can manage all contributions with final say on the main fork if there are any issues I guess

regards
Al

[Folknology]

Doug perhaps you can start a separate thread in the User area for this as a proposal so it can be moved forward, as this has pulled this thread off topic, best if it has its own thread.

regards
Al

[nassim]

Here's an idea:

1) The source of various documents is kept on github, and can only therefore be edited by contributors there (who we assume are pretty much trusted, and where there is complete ease to brand/revert changes etc, with no damage to reference copies)
2) This source is translated periodically into a wiki form, which is publicly-editable, and PDF form, which is posted on xmos.com
3) Periodically (before each source pull to the wiki) these suggested edits are curated by one or more github contributors back into the source on github. Goto 2).

Just a suggestion, but something like this would really help, and there are countless examples of people using far less restrictive processes than this to document commercial products.

for N°1 => i think is the best solution to use github as source documentation (only the contribute can edit)

for N°2 => i just create a group of tutorial and a wikiDoc => so i think we can add links of the source DOC (only PDF) in there http://www.xcore.com/wiki/index.php?tit ... E_Tutorial

and keep all member in forum and Wiki