[cifs-protocol] Bitfields in the WSPP docs

[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 at microsoft.com
Tel:  469-7757027 x 57027
---------------------------------------------------------------------


-----Original Message-----
From: cifs-protocol-bounces at cifs.org [mailto:cifs-protocol-bounces at cifs.org] On Behalf Of Andrew Bartlett
Sent: Sunday, September 13, 2009 11:59 PM
To: Interoperability Documentation Help
Cc: cifs-protocol at samba.org; docfeedback at thetc.org
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.