w3c
The documentation is confusing for people who aren't familiar with GH
A few people complained about the documentation not being clear or easy to read. From the different comments, it seems the different notions (travis, webhook, tokens, etc) are too complex and shouldn't be mixed altogether. One idea is to create 2 types of docs: beginners and advanced:
- beginners:
- how to create a token
- how to submit a tar or a url
- advanced:
- manifests for compound documents
- GH + travis (single spec per repo, multiple specs in one repo)
- respec documents and what spec-generator is actually doing
- upcoming support from bikeshed
In the long term, I prefer to have documentation on the Specberus/Echidna web pages themselves (and discard the GH wiki). It will allow us to structure things better, embed other content, etc. And it will be more consistent with the rest of the tools.
(Not to say I disagree with what you wrote; I'm just mentioning this to decide whether we'll continue extending the wiki, or start writing documentation on pages that will be served in the future at https://labs.w3.org/echidna/help/, or something like that. I prefer the latter.)
