Removing the developers guide

[Andrew Bartlett]

On Wed, 2013-08-21 at 15:48 +0200, Jelmer Vernooij wrote:
> On Wed, Aug 21, 2013 at 11:37:33AM +1200, Andrew Bartlett wrote:
> > On Tue, 2013-08-20 at 19:13 +0200, Jelmer Vernooij wrote:
> > > The developers guide seems to be fairly outdated at this point; it hasn't been
> > > updated in the last 10 years or so and its contents have little usefulness at
> > > best. Would anybody object to its removal?
> > 
> > Much of what is in there still looks valid, except particularly the
> > first chapter (on NT domain stuff better described in the WSPP docs). 
> > 
> > But the only way to tell if a bit of advise is out of date or not is to
> > already know the answer, a new developer would be overwhelmed, and the
> > rest of us just never read it.
> > 
> > I'm really not sure what to do with the rest.
> 
> A quick look shows that we should at least eliminate a large chunk of the
> developers guide. I think we should keep the rest around, but 
> a different format - one that is more easily editable by us - might be
> more appropriate. Perhaps just plain text files or restructuredText under
> devdocs/?
> 
> Part 1: The protocol
> 
> NetBIOS in a Unix World - better covered in the WSPP docs and Chris' book.
> NT Domain RPCs - mostly just an enumeration of the fields in various RPC
> 		 calls and structures from before the IDL days. Also
> 		 better covered in the WSPP docs
> 
> I don't think Part 1 is worth keeping around.
> 
> Part 2: Samba Basics
> 
> Samba Architecture (from '97) - explains some of the original decisions
>   behind the design of nmbd and smbd. Has some outdated and exaggerated
>   arguments about why nmbd and smbd are not threaded.
> 
>   I think this one should be removed.
> 
> The Samba DEBUG system - outdated but still useful. Perhaps this can
>   just be merged into the preamble for debug.h ?
> 
> Samba Internals - This is mostly about string and int conversion.
>   The int conversion seems to be covered equally well in byteorder.h
>   itself.
> 
>   The string conversion comments are mostly still relevant, but refer to
>   legacy behaviour from before 2000 and don't cover some of the newer
>   conversion functions.
> 
>   I think this would be confusing if we kept it around as is. Remove.
> 
> Coding Suggestions - Out of date; read the style guide and general
>   advice on contributing to FOSS instead. Remove.
> 
> Modules - Out of date. Remove.
> 
> Part 3: Samba Subsystems
> 
> RPC Pluggable Modules - No longer accurate. Remove.
> 
> VFS modules - No idea. Considering the VFS layer has changed quite a few
>    times since 2002 I'm going to guess it's out of date. 
> 
> The smb.conf file - Some short notes on the behaviour of the params.c.
>    Perhaps just fold this into the preamble of params.c?
> 
> Samba WINS internals - Short, not really internals, mostly comments on WINS
>    parameters and configuration. Remove.
> 
> LanMan and NT Password Encryption - Somewhat out of date but still useful.
>    Perhaps convert to a txt file?
> 
> Part 4: Debugging and tracing
> 
> Tracing samba system calls - These are just general hints on using strace, not
> 	Samba specific. This is well enough covered in other tutorials on
>         the web. Remove.
> Samba printing internals - Last updated in 2002. Still relevant?
> 
> Part 5: Appendices:
> 
> Notes to Packagers - Short and mostly outdated. The notes on versioning
>    should probably be moved elsewhere where packagers can more easily find it.
>    README.packaging?

Thanks for looking over it in more detail.  I agree on your triage
above.  I think moving it to Doxygen style comments in the right
subsystems (eg file preambles as you suggest) would be the best hope for
the future, as we seem to be attempting to keep some documentation in
that format. 

Andrew Bartlett

-- 
Andrew Bartlett
http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org
Samba Developer, Catalyst IT                   http://catalyst.net.nz