[Samba] DNS problems (still) with Linux domain members - using Samba's internal DNS backend

[Gary Dale]

On 2023-04-26 04:46, Rowland Penny via samba wrote:
>
>
> On 25/04/2023 22:59, Gary Dale via samba wrote:
>> I actually think you went in the wrong direction there. By removing 
>> the <some meaningful information>  and putting in just the actual 
>> values, it's harder to distinguish what is magic and what is 
>> user-provided. For example, in adding an A record, demo is the name 
>> of the new host being added while A is the record type being created 
>> and 192.168.0.55 is the IPV4 address of the demo host.
>>
>> I think it would be clearer to write the example as:
>> $ samba-tool dns add <dns server> <dns domain> <name to add> A <IPV4 
>> address to add> -U administrator
>>
>> The example now shows people unnecessarily writing the FQDN of the 
>> DNS server when only the name is really needed.
>>
>>
>> The omission would be a test that shows why my setup isn't working.
>>
>
> I give up, first you wanted genuine examples, now you want generic 
> examples, tell you what, would you like the chapta answer, so that you 
> can fix the wiki to your liking ?
>
> Rowland

I appreciate your efforts to make the wiki better. However, I spent some 
time talking about the use of bracketed values as the normal way to 
indicate that the user should replace them with their actual values so 
they could be distinguished from things that should be entered as is.

I only wrote on sentence about possibly giving an example "for added 
clarity" yet that is what you focused on. Now someone reading it has to 
puzzle out what are example values and what are fixed parts of the command.

When you know how to do something, it may be clear to you which is 
which. But when you are looking for instructions, you shouldn't need to 
read previous examples to figure out that some number (for example) is 
part of the server address and not a port assignment.

That's what makes writing good documentation difficult. You need to know 
the topic in sufficient depth that you have difficulty seeing it from a 
learner's perspective. I've been dealing with networking for decades and 
the documentation as written still trips me up because I have little 
experience with Samba's internal DNS backend.