Developer Documentation

[Charles N Wyble]

Andrew Bartlett wrote:

>On Fri, 2005-01-14 at 14:16 -0800, Charles N Wyble wrote: 
>  
>
>>Hello Everyone,
>>
>>    I have been following the samba technical list for a while (few 
>>months) now and have a suggestion. I see quite a few good tidbits every 
>>couple days on various portions of the code and good solid discussion 
>>quite  a bit on various samba aspects. I would like to propose 
>>documenting these items.  It is a shame to have to read the archives and 
>>pick out the gems. I enjoy doing it but then thats me :) I imagine most 
>>people don't have the time or motivation to do that. I am more then 
>>willing to help with the documentation and possibly lead the project. 
>>One caveat ..... I am fairly new to samba and so may have a lot of 
>>questions bout various aspects of it that I would want to explain in the 
>>documentation.  If you can put up with my questions and comments I would 
>>be happy to lead this project.
>>    
>>
>
>Developer documentation, and more particularly prospective developer
>documentation is perhaps one of the bigger 'holes' in the Samba project
>at the moment.
>
Yes. I noticed that when wanting to get involved with the samba4 effort.
Killing Active Directory is a major goal of mine. It  lines up with my goal
of killing exchange. While the code is fairly easy to read/follow there is
a lot of code. Heck even trying to understand the build process is a
challenge :)
One example of information I would like to capture and document is the
recent
thread on IDL compilers. A good healthy debate between knowlegeable
developers
and clearing up of various misunderstandings etc. Classic open source
development
methods at work. Or as so many signs around the LA metro area say.....
your tax dollars
at work. :)



>  Previously this also included the website, but thanks to
>the efforts of Deryck Hodge, we now have a very good website, and this
>gives me hope that this too can be be fixed.
>  
>
Yes. The website is superb. Great stuff. A very shining example. Good
job all.

>Many years ago, there was a 'Kernel Cousins Samba' (from Kernel-Traffic)
>that did a nice job of covering the samba and samba-technical mailing
>lists, and Deryck proposed here only a few months ago that he would like
>to see a similar thing revived.
>
Yes. His post was something that helped prompt me over the edge to take
the initative
and get this rolling.

>  It is not an easy task, particularly
>covering both samba-technical and #samba-technical, the IRC channel,
>where a lot of particularly Samba4 development takes place.  
>  
>
Yes. I have seen that to be true.  Would it be possible to have a log of
the chat mailed
every 24 hours? I think that would be a good idea.

>We do have a small collection of current Samba4 development
>documentation (such as prog_guide.txt, the talloc guide, as well as some
>parts of my thesis, vl's and my recent white papers),
>
Yes. I have read each and every one of those documents in detail. They are
great!! Very helpful and a good scattershot of information.

> as well as a large
>amount of increasingly out of date docs from Samba3.  Unfortunately,
>there isn't a nice big 'this hasn't been looked at for years' marker,
>which makes this a bit of a minefield.
>  
>
True. Do you want that added? If so I could do it. A watermark on every page
should suffice in my opinion.

>The reason that we have got into this state is that developers much
>prefer to develop, and there tends to be few who are in the loop enough
>to write things down, who don't want to spend time coding instead ;-).  
>  
>
Well. I may be your man. I am a fairly well skilled sys admin and entry 
level coder. I can read code and make mods and poke and prod/ cut and 
paste and make stuff work. As far as new/from scratch code I am not as 
well versed.

>I do hope you (or others!) can find some way to help digest this, into
>something more useful to prospective developers.

So do I Andrew so do I. Lets tap the masses of coders that are out there 
and don't like Microsoft. If they can put action to words and make samba 
bigger better faster cheaper.... (bionic samba anyone?) then the world 
will indeed be a better place.


-Charles
PS Andrew sorry bout the email off list. I hit send by mistake.