search

OpenCyphal / specification

The Cyphal specification documents are maintained here.
https://opencyphal.org/specification
Creative Commons Attribution 4.0 International
42 stars 12 forks source link

Proofreading of Chapter 3 - DSDL specification #48

Closed pavel-kirienko closed 5 years ago

pavel-kirienko commented 5 years ago

This PR is against the changeset of #46. It contains minor corrections and fixes across the whole specification, mostly focused on minor clarifications and fixing incorrect term usage. The bulk of the changes is due to the automatic replacement of patterns like node ID to node-ID. I have also updated the DSDL rendering script to use PyDSDL v0.5.0 and fixed its version to prevent future breakage.

Originally I planned to postpone opening this PR until the previous one is accepted, but then I noticed that the old PR is likely to raise questions which are already addressed here, so it seemed sensible to come forward with my changes even if that might disrupt the workflow somewhat.

The changes should be relatively easy to review in the source form right here on GitHub. This is not a WIP; if we agree on the changes, they should be merged immediately.

thirtytwobits commented 5 years ago

I have notes in the PDF up through Section 3.4 so far. I'm trying to finish this today (my time). I guess I can't attach the PDF to this PR so I'll go back through and c&p the comments into the source when I'm done.

thirtytwobits commented 5 years ago

Okay, wow. Totally underestimated the size and information density of chapter 3. First let me say, @pavel-kirienko , this is an impressive amount of work and, so far, seems to be well thought out.

My new estimate for completing my review is not end-of-week (April 20th).

hamishwillee commented 5 years ago

(I'm not sure if Hamish is still available for this work; if not, we'll hire someone else

@pavel-kirienko

If you find a tech editor who has experience in standards documentation go for it. While I can certainly identify wording that isn't clear or is awkward, standards review requires a degree of precision that I don't normally have to aspire to.

That said, I am available and willing to help over next month or so. Are you at the point where you need review? After that my contract changes and we would need to revisit.

pavel-kirienko commented 5 years ago

@hamishwillee Thanks! We are so very close to the final review. Once #46 is merged (I think we're almost there), I am going to minorly restructure the transport chapter, add a few elaborations into the non-normative introductory chapter, and that would be it. I will let you know once we're ready.