[Samba] Samba documentation team

Stuart Naylor stuartiannaylor at thursbygarden.org
Wed Apr 2 07:46:30 MDT 2014


https://pad.riseup.net/p/SambaDoc

Quoted again as I think the above is brilliant and really concise.
MySQL docs are rather good and a lot of top flight software is position on the value of its documentation.
Its a bit of plagiarism but MySql has the best normailsed documentation going, I guess it would have being MySQL.
I really don't think there is a better structure to documentation. The MySql guys have sort of boiled it down to such a pure functional level.
Its oracle now but they where not the format creators.

Real Life examples and step by step guides are hugely advantageous.
Often when I want to learn software a theoretical manual is just to much info.
I need to run the software. Its what I call the video recorder method.
No-one reads the manual and its only on your third episode of crufts that you really dig the manual out to set a timer to record the footie.

I posted some stuff that I have been working on and its taken a back burner whilst I hack webmin. (Could really do with some help)

Wiki's are great and I should contribute more. All that hassle of getting an account. Wiki formatting and if its going to be part of an official wiki then it should look the part.
Pffft! I have created a text file of a step by step cli command list with some brief annotation and I just want to post it.
Or a PDF or rtf or even word.

Why in opensource we have all these correct routes methods, structures and procedures its supposed to be open?

I am not going to post the link again because I think it got moderated.
I have been working on a platform that is all about opensource communities and some idea's how great software like samba can create revenue without affect any normal activities.
In fact samba don't even have to do anything. That is going a little further because going back a step is that we need something called an UnKE not wiki.
This is for unstructured documentation freely submitted and given value by the community, its just bog standard peer review.

So boiling it down its a hybrid of forum and social media newsfeed. It has a parent child categorisation system that breaks up the documentation.
The further you step down the child ladder the more specific the documentation becomes.
The complete activity of forum posts, blogs, video's, images blah blah are all listed in the newsfeed sorted by a couple of tabs.
Version, All time best, Whats Hot, New and My.

Being an ex DBA / Dev and coming back to the documentation is that the parent child ladder as a personal opinion should follow the documentation.
If you had that great structure of the MySQL documentation every contribution is categorised by its corresponding documentation and because of that every body knows what it pertains to.

The only other thing about documentation which I do think version is very important is to think of a documentation object model. Break it up to higher levels of abstraction that provide logical groupings.
Haven't a clue what they could be, but I am sure someone could figure them out.

I did post the website I am working on but as I said I think it got moderated. Its completely free, no ownership Samba team can have the domain if they want.

My thoughts are that you should have a official site of a very formal nature which is what you have and what seems to be proposed.

Then have a separate informal site that I call a Bazaar that is a community knowledge and contribution exchange.
I think it could provide much value and also create revenue for the project.

But going back to the documentation an UnKE that is sorted by what a community feels of is value is organic and free flowing and can change as a product changes.
It requires no workload unlike the effort to produce a polished wiki and negates the need for a few to work out what the many might value.

Just a thought

Stuart

:)

When I get a rough and ready webmin up and running I will return back to the Bazaar and again (anyone any good with php?)


 
-----Original message-----
> From:steve <steve at steve-ss.com>
> Sent: Wednesday 2nd April 2014 11:27
> To: samba at lists.samba.org
> Subject: Re: [Samba] Samba documentation team
> 
> On Tue, 2014-04-01 at 21:29 +0100, Stuart Naylor wrote:
> > Hi and wow, https://pad.riseup.net/p/SambaDoc
> > 
> > Much better than what I have been usuing.
> > 
> > Only thing I can is that probably some of the best documentation I have ever used was mysql.
> > 
> > Each version had its own documentation which was basically the same, always the same category headings and number system but with version taken into account.
> 
> There is also space in the mysql user docs for user examples and hints.
> What we lack in samba are real life examples in real life domains. Maybe
> add space for us to include our own comments? Easily? At the moment it
> needs a wiki account.
> Just our €0.02
> 
> 
> 


More information about the samba mailing list