> From: steve > > On Wed, 2013-07-24 at 09:09 +0200, L.P.H. van Belle wrote: > > > > I do like samba, but wiki/howtos are lots to improve. > > To be fair, it's not just Samba. It's most open source stuff. > There are > too many hobbyists and armchair users. As joe public, what we > should be > doing is not criticising the devs for their poor documentation. We > should be writing it ourselves at our own level. Let the devs enjoy > their C and let's thank them for the code. It's not down to them to > document it for end users.
It's a little hard to write documentation when all you've got is a million questions and no answers. The only people who actually have the answers are the developers. I wish developers would routinely budget, oh, 10% of their time to writing docs. I spend at least twice that much on documenting my own software, because I find it helps me write better organized code if I first have to explain what it's going to do, or how to use it. Write the manual first, then implement it, modifying the manual as you discover logical flaws during the process of writing and debugging. > I doubt that Microsoft would allow their > coders anywhere near the end user documentation department. I don't know what they do at Microsoft, but there must be some organized way of getting the software writers to convey the information to the people who actually write the documentation. In my opinion (as someone who's been spending a big chunk of his life reading documentation lately), the MSDN content ranges from marginal to excellent, while Linux-land documentation ranges from practically non-existent (e.g., ALSA) to very good (the kernel man pages). So far, I think Samba's docs get about a C-, but that's because I know next to nothing about networking; they may look much better to someone who already knows all about SMB from the Windows world. -- Ciao, Paul D. DeRocco Paul mailto:pdero...@ix.netcom.com -- To unsubscribe from this list go to the following URL and read the instructions: https://lists.samba.org/mailman/options/samba