RE: [odata] Not a request for change

[Michael Pizzo <mikep@microsoft.com>]

Yikes! Thanks for the comment Patrick.

The intention of the statement, I believe, was that you wouldn't need *custom* documentation for your API to be consumed by generic clients if you used OData, because an OData service is "self documenting" in that it exposes a machine-readable metadata document that describes the types, relationships, actions, and functions exposed by the service. That, together with the documentation of the OData protocol, is sufficient for generic tools, libraries, and applications to consume the service.

It is still important to document the *OData Protocol* (as you well know) and useful to describe the semantics of the entities, relationships, functions and actions exposed by the service for end users consuming the data.

I'm sure we didn't intend to say that documentation wasn't important, though I agree the choice of wording for that segment is unfortunate...

-----Original Message-----
From: odata@lists.oasis-open.org [mailto:odata@lists.oasis-open.org] On Behalf Of Patrick Durusau
Sent: Thursday, January 9, 2014 6:51 AM
To: odata@lists.oasis-open.org
Subject: [odata] Not a request for change

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Greetings!

I happened across the video on the home page of odata.org.

At approximately 1:12, "OData eliminates the need for documentation"?

I had to listen to it twice to be sure but that is what is said.

As a documentation person, I thought that was a rather odd claim to make.

I don't think anyone will take it seriously so no need to change it but it did get my attention. ;-)

Hope everyone is at the start of a great new year!

Patrick
- --
Patrick Durusau
patrick@durusau.net
Technical Advisory Board, OASIS (TAB)
Co-Chair, OpenDocument Format TC (OASIS) Editor, OpenDocument Format TC, Project Editor ISO/IEC 26300 Former Chair, V1 - US TAG to JTC 1/SC 34 Convener, JTC 1/SC 34/WG 3 (Topic Maps) Co-Editor, ISO 13250-5 (Topic Maps)

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJSzrdFAAoJEAudyeI2QFGo9fUQAIa32qlBAeKwOCo77gmWZYye
pYcDAkaDP239jBW0lbHEYEc6/IA2zf0HF6caBCw0YIrCAEmr7VIHONJifqPlFJtT
Sv+lVFdSPG/HKN4wmR1O9E6GIBCuh/o0cCnbM5iKeSfZO0Dc+0RFzrN7CaMsNDyc
nsNdgv7Jjkm/EN16dsVwsGjM5dPuexjYk5ofC5EqTI2NNs88/+QtRfUcI7uQBw34
pYQOfyHHDez7SjBoE8xJrckcuLzaLzohkt2/ah4dijone5J4EBZ/H0DdB5A1Tjrw
wvXjBoyhvKyl420AUwl+gPZcYkhxHOjVD6XVxylMoWZqTBhG0lzpbyRqHgNnlcB3
80AvPCCfSncXVX8yHsO1WEdUeEQHRLbdMHbt1AVqFU/jmWptDmJ1Qz0NIs+MExUH
WybCFmHeazIxRp/j3wCgIb4OCA3zILKGVNRWj3D/3Z++HeB4zYnR7N4nYntek6g/
xIKYFaDDd3KxI4yWJwlrULV+SkvnW9Q/dVieMU4SIR9dcJsWuIIjmS+PqbGAUttq
sIlaVVSzxkw7LZ6/64er6D4bcZtasQWE9LzefYdhtgDCcL/k8qg+l3vdAZlVcAJY
a7ZZekNA1rxEejpB/tyMjgGuvOWJU/PzYsPPR+UuN+2XFqpx20DcPmYexTDNEG3g
+mScd1LLNW+cetOE4EH3
=klBI
-----END PGP SIGNATURE-----

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php