Web lists-archives.com

Re: [Samba] Problem achieving manual synchronisation of idmap.ldb and the associated User and Group ID mappings between two Samba 4 AD DCs

On 26/03/2019 13:39, Rowland Penny via samba wrote
Go on, I give in, what is wrong with the official Samba documentation?

Off the top of my head:
1) Your (ie Samba project) docs are structured a little poorly and
actually pretty hard to follow - eg a single article describes
setting up Samba both with SAMBA_INTERNAL and BIND which is
confusing. Two separate articles, one on each topic would be better!
The problem is that the Samba wiki is written from the perspective of
using a self-compiled version of Samba, not from the perspective of
this is how you use Samba on distro X.
This is a big problem with your docs though. I am really not sure that is the right assumption to make from the viewpoint of actually driving Samba adoption in 2019. Yes, docs describing building from source are in theory universal, and there is the ever present problem of Linux fragmentation. However in reality I reckon probably 1% of your users build Samba for themselves from source. Most busy SysAdmins will be using either Debian/Ubuntu packages or CentOS/RedHat packages I would imagine, so you would only need two sets of docs to cover the vast majority of users.
Could you supply a link to the Samba dns page you refer to ?

The page in question isn't actually about DNS but it is the main Samba AD installation tutorial here:


This is the main page for Samba AD installation and wants to be split into at least 2 further pages IMHO to avoid confusion

1) Samba AD installation with SAMBA_INTERNAL backend

2) Samba AD installation using BIND backend

3) Possibly split again to describe interactive and non interactive installation with Bind and Samba_internal

3) They lacks the clear straightforward step by step approach of
TechMint with screenshots and similar?

Not really a fan of screenshots, unless there is no other way of
displaying information.

You do need some way of letting the user confirm *for themselves* that what they see on their own termnial is what they should expect to see. This lets them verify that they have set things up correctly. This is very important! Note that this doesn't have to be an actual picture screenshot, it could be some example terminal output. Something so they can verify that they are on the right track.

4) In practice this means that non-experts cannot / wont be able to
use Samba, even for basic tasks as I am trying to do here. People
less determined than me will give up,
and I am basically dependent upon this (awesome, thanks everyone)
mailing list and its support.
Again, the wiki was written from the point of view of experts and not
necessarily understandable by 'non-experts'. This needs to be fixed,
but to do this, we need to know what is actually wrong.
Even assuming your guide is for experts, one of the biggest problems biggest problem is there is no common thread or narative linking together separate disparate wiki articles on multiple individual topics. You could do worse than create a section on the Samba website - "Getting Started with Samba AD" that covers the top 5 basic use cases for Samba. Suggested structure:

Section 1) Setting up a primary DC

Section 2) Setting up a failover secondary DC

Section 3) Syncing primary and secondary DCs together

Section 4) Joining another machine to the Domain and setting it up as a fileserver

Section 5) Printer sharing

Section 6) Configuring windows clients to join a samba domain

Section 7) Advanced Samba Usage

5) You need to get one person to write the docs. Another person
should then separately *verify* the instructions that are given to
avoid simple mistakes.

This not entirely true, one person could do this, make notes as they do
something and then do it again, just following their notes.

The problem with the same person checking, is that a second person will take different approaches to the first and will encounter problems that the first person doesn't encounter due to different set of mental implicit assumptions etc. It makes your documentation more robust if a second person is involved in the validation.


To unsubscribe from this list go to the following URL and read the
instructions:  https://lists.samba.org/mailman/options/samba