Bitfields in the WSPP docs

[Andrew Bartlett]

Over a year ago, I wrote to this list about the incredible frustration I
suffer on a regular basis attempting to read and use the Microsoft
documentation.  

The problem was regarding the layout and incomprehensible system used to
describe the bitfields that occur in so many of the protocol documents I
use, and a year on, I was wondering if I had to reinforce my concerns.  

But there is hope - I've just seen a copy of the MS-CIFS document that
Chris Hertel has helped author (contracting to Microsoft), and I'm truly
amazed by the progress that has been made.   If this document survives
intact to final form, it will show that programmer-compatible
documentation can be produced within this framework.

To pick a random example, I see 2.2.4.43 'SMB_COM_WRITEX_ANDX'.  It
shows the format of the packet in a clear, text based format, replacing
the block diagrams, and the error codes are clearly given both textual
names and hexidecimal values.  (While it is incredibly disappointing to
no longer need to do 2^(n-31) in my head, I do find it a little
easier ;-)

It also puts to rest the incredibly insane 'bytes in little endian, bits
in big endian' that I have to say was so truly 'special'.

What I'm trying to say is that I really, really appreciate the
improvement.

These make the documents the single best example of network interface
documentation formatting that I have seen from this protocol program, I
strongly hope that whatever challenges have prevented the use of such
clear language in other documents might finally have been overcome, so
that other critical documents, the RPC documents in particular, can also
benefit from this treatment.

Thanks,

Andrew Bartlett

--
Andrew Bartlett                                http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org
Samba Developer, Cisco Inc.


_______________________________________________
cifs-protocol mailing list
cifs-protocol@...
https://lists.samba.org/mailman/listinfo/cifs-protocol

[Hongwei Sun]

Andrew,

  Thanks for the valuable feedback that is very important for us to continuously improve the protocol documentation.  We will definitely consider your suggestion and we can also have further discussion during IO Lab next week.

Thanks!

--------------------------------------------------------------------
Hongwei  Sun - Sr. Support Escalation Engineer
DSC Protocol  Team, Microsoft
hongweis@...
Tel:  [phone] x 57027
---------------------------------------------------------------------


-----Original Message-----
From: cifs-protocol-bounces@... [mailto:cifs-protocol-bounces@...] On Behalf Of Andrew Bartlett
Sent: Sunday, September 13, 2009 11:59 PM
To: Interoperability Documentation Help
Cc: cifs-protocol@...; docfeedback@...
Subject: [cifs-protocol] Bitfields in the WSPP docs

Over a year ago, I wrote to this list about the incredible frustration I suffer on a regular basis attempting to read and use the Microsoft documentation.  

The problem was regarding the layout and incomprehensible system used to describe the bitfields that occur in so many of the protocol documents I use, and a year on, I was wondering if I had to reinforce my concerns.  

But there is hope - I've just seen a copy of the MS-CIFS document that Chris Hertel has helped author (contracting to Microsoft), and I'm truly
amazed by the progress that has been made.   If this document survives
intact to final form, it will show that programmer-compatible documentation can be produced within this framework.

To pick a random example, I see 2.2.4.43 'SMB_COM_WRITEX_ANDX'.  It shows the format of the packet in a clear, text based format, replacing the block diagrams, and the error codes are clearly given both textual names and hexidecimal values.  (While it is incredibly disappointing to no longer need to do 2^(n-31) in my head, I do find it a little easier ;-)

It also puts to rest the incredibly insane 'bytes in little endian, bits in big endian' that I have to say was so truly 'special'.

What I'm trying to say is that I really, really appreciate the improvement.

These make the documents the single best example of network interface documentation formatting that I have seen from this protocol program, I strongly hope that whatever challenges have prevented the use of such clear language in other documents might finally have been overcome, so that other critical documents, the RPC documents in particular, can also benefit from this treatment.

Thanks,

Andrew Bartlett

--
Andrew Bartlett                                http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org
Samba Developer, Cisco Inc.
_______________________________________________
cifs-protocol mailing list
cifs-protocol@...
https://lists.samba.org/mailman/listinfo/cifs-protocol