https://bugs.openldap.org/show_bug.cgi?id=10257

--- Comment #1 from ireneista@irenes.space --- I hope it's okay to weigh in here (I mean, you asked me to, but I don't want to intrude or pile on...). As context for others, I have been working through the docs as a first-time user this week and I hope this is a productive place to put my thoughts. As a start on that, I've read through the assessment.

Overall the commentary in the assessment seems solid.

I found the documentation to be overall readable and pleasant. I endorse the idea of taking a pass to tighten up wording, just on the general principle that that's always a good idea, though I don't personally see it as urgent or anything. I do come from the cultural background the docs are expecting though, just to note that bias.

As somebody who does find formal grammars immensely useful when learning new syntaxes, and has specifically referred to the slapd config grammar several times even just in the couple days I've been using the project, I want to put in a plug for keeping the grammar. I have no opinion on what happens to the grammar organizationally (spun off or kept where it is), and I agree that it would make sense, as the assessment suggests, to augment it with plain-English description. I would find such description to be more time-consuming and difficult to work through both for initial learning and for later reference, so I wouldn't want it to be the only thing. I am always grateful when documentation of complex formats includes a grammar for them, and this is no exception.

As a higher-level point about the grammar, I think it's appropriate for a document like this to have content that's aimed at experienced programmers, as long as it's not exclusionary of people with different backgrounds.

I like the suggestion to structure documents as tutorial/how-to/explanation/reference. I usually gravitate towards reference and conceptual-explanation areas of documentation, and I've found that having stuff cleanly separated by purpose helps me do that. I'm sure most people have the opposite preference, which is reasonable enough, and these kinds of structure frameworks seem to help with that, too.