search

openlcb / documents

The OpenLCB specification: standards, recommended practices and other documentation.
3 stars 7 forks source link

WIP: updating wording in Read Command section and fix incorrect section re… #85

Open rm5248 opened 1 year ago

rm5248 commented 1 year ago

…ference

See: https://groups.io/g/openlcb/topic/98878366#14971

rm5248 commented 1 year ago

New table for section 4.4 that makes more sense to me, explicitly showing that the data in byte 6 can change depending on the value of byte 1: Screenshot from 2023-05-14 13-31-12

The other tables in the standard look fine to me, I don't think that they would have to change at all.

bobjacobsen commented 1 year ago

I agree the change to the table is an improvement.

The tables in sections 4.5, 4,6, 4.7, 4.8, 4.9, 4.10, 4.11 and 4.12 all have similar structure. I think they should get the same update.’

The language on lines 18-21 should also be changed.

balazsracz commented 1 year ago

I disagree with this pull request. I specifically posted two concerns on the email thread referenced, and this pull request does not address either of those two concerns:

I don't actually think the first concern can be addressed before addressing the second concern. So my question really is how do you propose to avoid the information duplication.

rm5248 commented 1 year ago

I disagree with this pull request. I specifically posted two concerns on the email thread referenced, and this pull request does not address either of those two concerns:

* there are many tables (Bob pointed this out as well)

Yes, this is a draft to solicit feedback. The other tables can be updated as well, I haven't done that as I want to solicit feedback on this section first before making the same changes to other tables.

* now there is duplication of information in the standard, which is a significantly worse presentation that carries forward risks.

Please inform me as to what information you feel is duplicated and why that duplication is bad.

atanisoft commented 1 year ago

why that duplication is bad.

Duplication of information can be bad when it is spread across multiple documents as they will invariably get out of sync and become a maintenance issue. If the information is contained solely within a single document (S, TN, WN, etc) then it should be less of a concern.