Hello,
Some thoughts I have had about OpenLDAP Documentation over the weekend ....
My overarching concern is one of process. My day job is Ops, and especially at scale a documentation process is critical to success. And what this boils down to is that:
- checking documentation is a part of the routine Ops process
- refining that documentation so that it is on-point, concise, and relevant is part of the Ops process
- when the documentation proves insufficient, the matter can quickly be escalated with Experts
- review of documentation is a routine duty of the Experts, and is part of the process of deploying new infrastructure
With this framework (paraphrasing
ITIL and
KCS) in mind, some reactions to my experiences with your community and the recent thread:
Efficient KnowledgebaseThis is always a tricky nut to crack ... people love Stack Overflow these days ... there's an existing corpus in the mailing lists. One thing I have done in the past is tie in resources with Google ... might be helpful to if
this page had a Google custom site search ..
I just tried setting one up to search all of the mailing list archives, issue tracker, F-o-M, stackexchange and serverfault "openldap" keywords ... I am underwhelmed at the results but you folks might have some better idea of "hot topics" and strong resources to try.
Howard Chu pointed out that he has configured F-o-M to show him dates ... maybe this can be the default? ;)
If you can get something good running, it makes answering some dumb questions on the list easier .. you can politely point them to the search with the appropriate keywords .. a la "let me google that for you" and the clever ones will catch on ... if you find the search mechanism less than clear, then maybe some of the docs can be tweaked a bit for keyword-matching, or be revised to cover a more general case or an example ... when a user asks me a dumb question, I try to step through how they would get the answer ... sometimes that stepping needs some help on my part, but on a good day I teach a user to fish ...
Ease of Updating Documentation
I had no idea but it looks like anyone can contribute to F-o-M. Nice. Let us, say, however, I had questions or amendments or heck contributions to the quick start guide?
http://www.openldap.org/doc/admin24/quickstart.html There's a footer at the bottom that implies the content is five years old and I'd bet $2 based on personal experience that I am not getting good answers from info@OpenLDAP.org. A contrast I dealt with recently is, say,
this Ansible tutorial ... at first, it seemed weird to host documentation on github but there on the top page they get to explaining that they are open to community contributions: fork, pull request, &c. I made some modest contribution myself: one of the first pull requests I ever made. Felt great. I then made some amendments to the GWM project, as their documentation is similarly hosted in a format I already know how to contribute to. :)
So, Howard Chu says OpenLDAP will never rely on github. Fair enough ... as an aside, I have seen at least one project maintain a github repo as sort of a managed two-way mirror to their traditional repo: this was done by contributors who wanted to hack around on the code in a convenient tool, and then patches are evaluated and brought into not-git core ... which is to say you could, if you desired, use github without relying on it ... but anyway ...
this comprehensive document could have a section on engaging the authors and the process of contributing amendments, maybe linked from the footer, which could have a dynamic bit of code that shows the current year (or last modified year?) so as not to scare anyone that the living documentation is crazy stale.
Documentation as Part of Deployment This struck me in my recent discussion around troubles with the Quickstart guide: when I went to use the quickstart guide, the documentation did not match the software, because the software had recently been changed. Best practice would be to bundle documentation updates in to the release. If, in my own Operations, I deployed changes to a service without reviewing and amending the Operational documentation, the nicest word I could use to describe that is "messy."
Tone
The attitude I have witnessed and experienced on the mailing list is off-putting. For example, I recently needed to re-order ACL rules, but as part of that I would be changing the order of rules I depended on to make the modification. Classic "lock yourself out of the firewall" setup. So, I used Google, dug around in the documentation, hoped that such a reasonable question would be covered in the F-o-M .. nada .. so, resort to mailing list. At least in this case, I did get
a workable answer: "the operations are atomic. Read this link where I condescendingly link to a decade-old draft spec .. ya moron."
In olden times, I was told to
go RTFM more politely: "base64 just makes the answer look different, see the mailing list for previous discussions (although you've already tried and failed to find the discussions alluded to..)"
People ask questions. Some are lazy or ignorant, perhaps, or really suck at asking useful questions. Some mean well, just don't know where to find the answer, but put some effort into trying to engage constructively ... I deal with folks on this spectrum all the time in my day job, and yes sometimes I want to bite someone's head off, but it doesn't help. It takes some patience and a deep breath and a lot of effort that may not seem worthwhile but when you offer offer friendly advice you gain allies who might stick around and contribute ... if you want to be a surly curmudgeon then you don't gain allies ...
My own take would be if a question just looks like lazy crud, offer some gentle advice as to the process of figuring it out "here's a link to our getting support guide" ... if a question sounds like it has been covered somewhat, ask how would that answer be revealed ... how would you search that the questioner did not ... maybe you've got half an answer but it really ought to be fleshed out ... you can task the person asking that once they figure it out, they post the solution in the F-o-M ...
Cheers,
-danny
--