[Samba] Samba documentation team

Mon Mar 24 12:52:39 MDT 2014

On Mon, 2014-03-24 at 11:50 -0700, DNK wrote:
> On Mar 24, 2014, at 10:51 AM, Marc Muehlfeld <samba at marc-muehlfeld.de> wrote:
> 
> > Am 24.03.2014 15:56, schrieb DNK:
> >> I’m too new with Samba to effectively add to the
> >> documentation, ...
> > 
> > You can help anyway. It would be good if we have someone who is new with Samba AD or Samba in general. Because people with more experience surely forget to mention steps in the documentation. So validating the documentation and proofreading would be an important part.
> > 
> > I hope to see you later in IRC, too. :-)
> > 
> > 
> > Regards,
> > Marc
> > 
> 
> This is true. I have been making notes and such on my installs. I tend to make them as “cookbook” as possible. I’m currently traveling for work in Mexico, and IRC (and many other things too) is blocked where I am… And the powers that be will not release it. I’ll watch the list and see what I can do upon return to Canada.
> 
> D
> 
Here it is so far:

menu
Status #samba-documentationX
(no topic set)
[19:04] == alicante [d946f7ea at gateway/web/freenode/ip.217.70.247.234]
has joined #samba-documentation
[19:04] <Marc_M> hey some more :-) welcome
[19:05] <alicante> Hi
[19:05] <Marc_M> not everybody needs to write documentations (and not
everybody likes to)
[19:05] <Marc_M> but we need more that just writing
[19:05] <antun> Hello :)
[19:05] <alicante> For beginners, it's best if beginners write the doco.
[19:05] <Marc_M> we need people proofreading (my english isn't perfect,
as you see) :-)
[19:06] <alicante> devs or those mor experienced assume too much
[19:06] <antun> Mine is not perfect to
[19:06] <Marc_M> and of course we need some knowledge and background
information, we maybe don't have
[19:06] <antun> but, I think that in this tehnical literature perfect
grammar is not as important
[19:06] <Marc_M> thats where we need the developers (but of course they
can help writing too )
[19:07] <crh> Good grammar allows you to express yourself more clearly,
and also earns the respect of the reader.
[19:07] <dcmwai> I've one question.
[19:07] <dcmwai> due to the fact that samba are moving fast.
[19:08] <antun> we can do it like Linux pipes do it "documentation"|
validation|grammar
[19:08] <fraz1> there are so much documentation available, most of them
are outdated
[19:08] <fraz1> There are different plattforms,
(wiki/www/,by-example/...)
[19:08] <fraz1> somebody has to point out the way ...
[19:08] <crh> dcmwai: Go ahead...
[19:08] <dcmwai> the docs we wrote/ proof read migh just get outdated at
the time it publish.
[19:08] <antun> yep
[19:08] <antun> I don't think that it would be outdated at that time
[19:09] <antun> Old ~2003 docu books are stil valid in many cases
[19:09] <dcmwai> antun, that depend on how fast we update it.
[19:09] <crh> dcmwai: Good point, but not entirely a problem.  I've been
working on Samba for 15 years now.  There is much that remains the same.
[19:09] <crh> Because much remains the same, changes are easier to
identify.
[19:09] <dcmwai> crh, true.
[19:10] <Marc_M> i think some of the old documenation should be there,
because many are still using it as a NT4 domain.
[19:10] <fraz1> what is the prefered plattform, who is allowed publish?
[19:10] <hartnegg> A lot of current docs are so badly outdated that they
are misleading, and they do not even say for which version they are.
[19:10] <Marc_M> but i think the wiki should have the direction: Samba
AD
[19:10] <hartnegg> But the wiki must also point people to the right
place when they only want a plugin replacement for samba 3
[19:10] <antun> There should be a strict distinction between Samba AD
and samba file server
[19:10] <dcmwai> but question are. when we update did we just drop the
old change?
[19:11] <alicante> Mark any docs clearly. This applies to 'NT', 'this
applies to Samba4 AD'.
[19:11] <dcmwai> I think the docs should have a version tags.
[19:11] <Marc_M> let me explain my thoughts
[19:12] <Marc_M> my idea is that all content should be written in the
wiki (everyone can register and add/update/...)
[19:12] <Marc_M> my idea is to create a table of content page
[19:12] <dcmwai> Marc_M, ya i like wiki ;)
[19:13] <Marc_M> a page isn't just a link page to some howtos
[19:13] == jakub__ [~jakub at ip4-83-240-85-23.cust.nbox.cz] has joined
#samba-documentation
[19:13] <Marc_M> i think about a table of content like the one in the
samba3x howtos (like here:
https://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/)
[19:13] == jakub [~jhrozek at adsl-ull-61-39.49-151.net24.it] has quit
[Quit: Leaving]
[19:13] == jakub__ has changed nick to jakub
[19:13] <antun> ok, we should have and index
[19:13] <Marc_M> and all entries in the toc can already be links to
non-existing pages
[19:14] <Marc_M> but then we can fill them more easily
[19:14] <Marc_M> and the documentation gets a good structure
[19:14] <Marc_M> and if content to the different topics is publishes,
its fine and available
[19:15] <Marc_M> but some of us (best would be a native english
speaker), could proofread and correct
[19:16] <alicante> We have a volunteer over on the samba list
[19:16] <antun> where should the documentation start? Should it start
with basic explanation of what a samba is, what operational modes it
supportm and how it compares to windows? What do you think?
[19:16] <Marc_M> the linked content could have side notes for specific
version if there's something different. but if something would have to
much expections, it should be on a new page
[19:16] <fraz1> what is happening with pages like this:
[19:16] <fraz1> https://wiki.samba.org/index.php/1.0:_Configuring_Samba
[19:16] <fraz1> good but really displaced?
[19:16] <Marc_M> so this is my idea how we could start a documentation.
what are your thoughts about it?
[19:17] <Marc_M> outdated @fraz1
[19:17] <fraz1> there is documentations for the difrferent levels
necessary
[19:17] <Marc_M> and of course we should try to move outdatet
information in the wiki to a tagged place (index.php/outdated/....)
[19:18] <antun> that's a good idea
[19:18] <fraz1> beginner/normal/experienced/develeper ..
[19:18] <Marc_M> i would not break the documentation down to so many
levels. why not have one documenation, containing everything detailed
[19:18] <Marc_M> like the samba3x howto
[19:19] == Davor_ [53ff350b at gateway/web/freenode/ip.83.255.53.11] has
joined #samba-documentation
[19:19] <antun> should we first create index page and then start writing
related pages?
[19:19] <Marc_M> because if you have n versions of the same thing,
changes have to be done in all
[19:19] <Marc_M> i think its not maintainable
[19:19] <fraz1> there is also knowledge about the wiki necessary, to use
the features:
[19:19] <fraz1> https://wiki.samba.org/index.php/Special:SpecialPages
[19:20] <hartnegg> Beginners can just skip sections, for example
bind-dns, or clustering.
[19:21] <antun> should we have examples for each distro?
[19:21] <Marc_M> yes. but who is intested, can go deeper
[19:21] <dcmwai> Marc_M: I wonder if we can have a guide of version
dependent
[19:22] <dcmwai> Meaning to say that.
[19:22] <Marc_M> i think its not maintainable if you have examples for
all. but notes about specific pitfalls, etc. should be there
[19:22] <dcmwai> All the version are there. But when select certain
version.
[19:22] <dcmwai> The other part are filtered
[19:23] <hartnegg> A Wiki can probably not do this
[19:23] <Marc_M> how can we handle a version depented documentation?
[19:23] <dcmwai> I thinking of a tag.
[19:23] <Marc_M> i would have the documentation valid for the maintained
version (currently 4.0 and 4.1)
[19:23] <antun> can wikimedia support tags
[19:23] <dcmwai> Something similar to how wiki handle translation.
[19:24] <Marc_M> older version of a document users can find in the
history
[19:24] <fraz1> mediawiki is able to do tags
[19:24] <Marc_M> can the tags be version specific fraz1?
[19:24] <dcmwai> Marc_M: I don't think the history will server us we'll.
[19:25] <hartnegg> The startpage should be some meta-index pointing to
samba3, samba 4 as file server, samba 4 as nt-dc, samba 4 as ad-dc.
[19:25] * crh would be happy to see pages that go into successively more
depth as you read further.
[19:25] <antun> if for example we write a documentation for dns. Sould
there be different pages for each version, or should we create general
document and then below that document write version specific nodes
[19:26] <Marc_M> @antun: this could be a good idea
[19:26] <dcmwai> antun: But is also make docs obsolete faster.
[19:26] <dcmwai> And become unmaintain or unmanag
[19:26] <dcmwai> Or orphaned soon.
[19:27] <Marc_M> but the main document could be about the maintained
versions. and at the end of the document we can have version specific
information
[19:27] <Marc_M> then all about that topic is in one doc - including
version specific stuff
[19:28] <antun> and maybe at the end, or near the end we could have
table with links that explain how to setup dns for each distro
[19:28] <antun> ?
[19:28] <antun> i think that having complete walkthrough for each
platform is a must have
[19:28] <antun> by platform i mean a distro
[19:28] <Marc_M> if the footnotes are to many, they can be split to a
different page and linked
[19:28] <fraz1> the most importent task in a wiki is the naming of a
document. Is the name wrong nobody understand it later
[19:29] <fraz1> this is fine.
[19:29] <fraz1> Samba4-Dependencies
[19:29] <fraz1> Samba4/Build Status
[19:29] <fraz1> Samba4/Buildfarm
[19:29] <fraz1> Samba4/DomainMember
[19:29] <fraz1> Samba4/HOWTO/Setup a Single Sign-On Website
[19:29] <dcmwai> fraz1: Had a good point.
[19:29] <fraz1> Samba4/LDAP Backend/OpenLDAP
[19:29] <fraz1> Samba4/LDB/Partition/API
[19:29] <fraz1> Samba4/MIT KDC
[19:29] <fraz1> Samba4/MissingSymbols
[19:29] <fraz1> Samba4/OSX
[19:29] <fraz1> Samba4/ProvisionIssues
[19:29] <fraz1> Samba4/Releasing
[19:29] <fraz1> Samba4/SWAT
[19:29] <fraz1> Samba4/Todo
[19:29] <antun> we must be able to explain how to setup a complete
windows server replacement
[19:30] <fraz1> please take a lot at samba by example
[19:30] <Marc_M> i think i would not only rely on the search engine in
the wiki. with a table of content, the users can easily be guided
through the documentation and they can find stuff that is related
[19:30] <antun> and explain all the differences so that the windows
admins can handle the complexity
[19:30] <dcmwai> antun: There are many way to do that. And it is not a
single router
[19:30] <hartnegg> wiki.ubuntuusers.de has version-specific examples
embedded inside the pages, this works quite well.
[19:30] <antun> single router?
[19:31] <dcmwai> antun: Single route
[19:31] <dcmwai> Typo
[19:31] <hartnegg> currently most linux distros do not support samba4
well, we cannot know how this will develop
[19:31] <Marc_M> @hartnegg: do you have a link or an example
[19:31] <antun> by many i mean debian, ubuntu, and centos
[19:32] <gladiac> re
[19:32] <fraz1> ubuntu 14.04 and debian jessy will have samba4
[19:32] <Marc_M> i think the samba documentation should be most distro
neutral.
[19:32] <fraz1> so samba 3 is dead
[19:32] <gladiac> Marc_M: I agree
[19:32] <Marc_M> otherwise you have an endless work
[19:32] <fraz1> it is out of maintenance
[19:32] <Marc_M> you cant mantain any more
[19:32] <crh> Samba 3 is legacy
[19:33] <ddiss> hartnegg: I think you're referring to feature support
(AD DC), not version support
[19:33] <Marc_M> and many distros have their own documentation (like
ubuntu) for samba
[19:33] <gladiac> Samba 3 is in security fixes only mode
[19:33] <hartnegg> samba3 is soon dead, but samba4 as file server
without ad is not dead.
[19:33] <gladiac> It will be EOL with the release of Samba 4.2
[19:33] <fraz1> whe need samba by example for samba4
[19:33] <hartnegg> ubuntu docu for samba is horrible, lags behind more
than a year
[19:33] <Marc_M> yes  @fraz1
[19:34] <gladiac> We should move as much as possible documentation to
the Samba Wiki
[19:34] <fraz1> yes
[19:34] <Marc_M> thats why my idea was to create a good table of content
and then start filling the linked pages
[19:34] <fraz1> what will the developer doß
[19:34] <Marc_M> what do you think about that idea?
[19:34] <antun> should there be an analogy to windows configuration?
[19:35] <fraz1> what does this mean?
[19:35] <Davor_> I'm missing a section where Samba team is stating what
is to be done to the next monthly service release.
[19:35] <antun> if for example set a share i samba, this is the same as
clicking on the windows folder and enabling the share
[19:36] <antun> i did a huge ammount of typos
[19:36] <gladiac> Davor_: that it is often hard to say
[19:36] <Davor_> I see.
[19:36] <fraz1> we need it! because we are working with windows guys
[19:36] <gladiac> https://wiki.samba.org/index.php/Samba_Next_Goals
[19:36] <gladiac> This is a overview of what we are working on
[19:36] <Marc_M>  @davor_:
https://wiki.samba.org/index.php/Samba_Next_Goals
[19:36] <fraz1> history ->
[19:37] <fraz1> (cur) (prev) 11:09, 20 September 2013 Metze (Talk |
contribs) (2,469 bytes) (reference DCERPC and Samba3/SMB2 pages)
[19:37] <fraz1> (cur) (prev) 22:23, 5 September 2013 Abartlet (Talk |
contribs) (2,548 bytes) (change how we express the
[19:37] <gladiac> currently is is mostly changing and improving low
level functionality
[19:37] <gladiac> so 4.2 will not have that many new features
[19:38] <antun> so what did we conclude so far
[19:38] <fraz1> next goal is something like embeded git
[19:39] <dcmwai> sorry..
[19:39] <dcmwai> I know that samba 3 is EOL in somewa
[19:39] <dcmwai> but still much of the question pop in mailing list are
part of it
[19:39] <Davor_> gladiac & Marc_M: Thanks for the link.
[19:39] <dcmwai> at least if you check samba there are alot
[19:39] <Marc_M> the questions are about samba as a nt4 PDC
[19:40] <Marc_M> for that you can use 4.x too.
[19:40] <Marc_M> samba4 != AD only
[19:40] <dcmwai> Marc_M, or Samba as DC member
[19:40] <dcmwai> Marc_M, not all people have to change/upgrade
[19:40] <fraz1> samba3 fits to windows xp. I need smb3
[19:40] <antun> we should explain that samba has two general  types of
modes: samba as file server, and samba as domain controller
[19:40] <dcmwai> fraz1, yes..
[19:40] <fraz1> for windows server 2012
[19:41] <dcmwai> Marc_M, so i do hope that we can still maintain samba
3.6.x docs
[19:41] <dcmwai> at least for sometime..
[19:41] <gladiac> dcmwai: Samba 4.x provides all functionality of Samba
3
[19:42] <Marc_M> theres no need for special 3.x docs. all can be done
with 4x too
[19:42] <crh> The Samba4.x file server engine is based on the Samba 3.6
engine.
[19:42] <gladiac> So most docs for Samba 4.x are valid for Samba 3.6.x
too.
[19:42] <dcmwai> as per said if these are common area, samba4 docs can
use it as well.
[19:42] <Marc_M> i think the documentation should be only about the
maintained version (currently 4.1, 4.0)
[19:42] <antun> but there are so many people using older versions
[19:43] <Marc_M> maybe the security-only tree as well
[19:43] <fraz1> in cause of the enterprise distros :-(
[19:43] <antun> and like crh said file server code is mostly the same
[19:43] <Marc_M> but i think we should not spend time with writing
documentation about version that are not maintained any more (3.5... or
some still using 3.0)
[19:44] <antun> the documentation for most of 3.0 code is already
available
[19:44] <antun> but for version 3.6 may not be up to date
[19:44] <fraz1> the problem is to workout the differences ...
[19:44] <Marc_M> and i would not start writing docs for 3.6, as 4.2 is
comming soon
[19:44] <Marc_M> it wouldnt be ready before it is end of life
[19:44] <gladiac> Samba 4.x provides all functionality of Samba 3!!!!
[19:44] <hartnegg> old docu should get notes telling that it is old,
especially all in www.samba.org/samba/docs/using_samba
[19:44] <antun> ok I agree, but for example, rhel uses older samba
[19:45] <gladiac> Only some 'securty' have been removed and they are
already deprecated in 3.6
[19:45] <antun> and if I am not wrong they backport the security patches
to older versions
[19:45] <gladiac> so the documentation is still the same
[19:45] <fraz1> @gladiac push it into the distros
[19:46] <crh> It would be nice to have the update history for each page
included at the bottom of the page.
[19:46] <gladiac> fraz1: yes, if a distro uses an old unmaintained
version it is their task to document features they provide
[19:46] <alicante> 80% of questions on samba at lists.samba.org are: DNS,
difference between DC and file-server roles, uid:gid mapping, rfc2307
and replication issues.
[19:46] <Marc_M> @crh: i think this would generate a very long doc some
day. and the wiki history of each page is just one click away
[19:46] <fraz1> @crh this is the part of the wiki engine
[19:47] <antun> we should also create documentation for how to write C
vfs modules
[19:47] <crh> antun: Such documentation exists, but is stand-alone and
out of date.
[19:47] <antun> we should update it
[19:47] <crh> :)
[19:47] <antun> and it would be good to write a documentation of how
samba works internally
[19:48] <fraz1> this only can done by a developer ...
[19:48] <gladiac> Well, you should first focus on the missing and
important parts
[19:48] <antun> so that people willing to help with the code can more
quickly dive in
[19:48] <crh> Marc_M and fraz1:  You are correct on both counts, but one
of the things that I find most frustrating is not knowing how old a
piece of documentation is and who wrote it.
[19:48] <hartnegg> vfs modules and internal gears could go into
appendixes
[19:48] <gladiac> antun: for VFS module documentation you should talk to
Richard
[19:48] <gladiac> crh: See the wiki history ;)
[19:48] <Marc_M> @crh: at the end of each wiki page, you find a
timestamp and in the history of each page, you can see previous version
[19:48] <antun> what I am trying to say that all that sould be
documented
[19:48] <dcmwai> winbind is one of the headache
[19:49] <Davor_> Is there a section about the different server services
in DC mode?
[19:49] <crh> antun, fraz1:  I would love to see Doxygen documentation
within the Samba code.  Alas...  
[19:49] <gladiac> I think we should start with what alicante described
[19:49] <dcmwai> Davor_, no.. I didn't see that
[19:49] <crh> gladiac, Marc_M:  That's good if the documentation is in
Wiki format.  I've been working with Samba a long time, I guess.  I'm
used to seeing lots of stuff with no timestamp or history.  :p
[19:49] <gladiac> crh: That's what I'm working on for years ...
[19:50] == kopernikus [~Thunderbi at canon.lpg.tu-cottbus.de] has joined
#samba-documentation
[19:50] <Marc_M> @crh: do you have an example?
[19:50] <gladiac> crh: and normally I give a NAK if a patch doesn't
contain doxygen documantation in the meantime
[19:50] <crh> gladiac: The last time I tried to add Doxygen to some
recent code (you know which) it got NAKed.
[19:51] <dcmwai> crh, that why I say..
[19:51] <fraz1> what is the way to generate wiki from doxygen?
[19:51] <dcmwai> version tag are important
[19:51] <dcmwai> crh, or something similar
[19:51] <dcmwai> crh, without that it will be just mess
[19:52] <crh> Marc_M:
https://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/  ...which
is quite out of date, of course, but I see no timestamps.
[19:52] <gladiac> crh: Submit patches with only doxygen documenation,
and please follow the syntax we already use. See talloc, tevent and
tdb ;)
@jelmeralicanteantunchsccrhDavor_dcmwaiddissfraz1gladiachartneggjakubkopernikusLumienkeliMarc_MRiXtEr