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 https://en.wikipedia.org/wiki/Problem_management#Problem_investigation_and_diagnosis and KCS http://library.serviceinnovation.org/KCS_Practices_Guide_v6) in mind, some reactions to my experiences with your community and the recent thread:
*Efficient Knowledgebase*
This 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 http://www.openldap.org/lists/ had a Google custom site search .. I just tried setting one up https://cse.google.com/cse/create/congrats?cx=015007933238430841659%3Auvkt3qcioho 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 https://github.com/leucos/ansible-tuto ... 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 http://www.openldap.org/doc/admin24/ 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: http://www.openldap.org/lists/openldap-technical/201603/msg00057.html "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 http://www.openldap.org/lists/openldap-software/200102/msg00345.html: "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
Daniel Howard wrote:
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 https://en.wikipedia.org/wiki/Problem_management#Problem_investigation_and_diagnosis and KCS http://library.serviceinnovation.org/KCS_Practices_Guide_v6) in mind, some reactions to my experiences with your community and the recent thread:
*Efficient Knowledgebase*
This 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 http://www.openldap.org/lists/ had a Google custom site search .. I just tried setting one up https://cse.google.com/cse/create/congrats?cx=015007933238430841659%3Auvkt3qcioho 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.
What's wrong with google "site:www.openldap.org etc etc etc" if you like searching with google?
Howard Chu pointed out that he has configured F-o-M to show /him/ dates ... maybe this can be the default? ;)
Maybe it's futile to invest more energy in written documentation when users already don't read what exists?
*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 https://github.com/leucos/ansible-tuto ... 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. :)
And again, you're talking as if these things don't already exist, when they obviously already do. The /doc/ subdirectory of the source tree contains all of this. Clueful contributors will see it and know it immediately. Clueless wannabe contributors will just waste your time asking for things to be created that have already existed for years.
*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."
Again, the documentation *is* bundled with our releases. If you didn't read your own local copy, that's not our fault and we can't help you to know what's already installed on your own machine. That's your responsibility.
In olden times, I was told to go RTFM more politely http://www.openldap.org/lists/openldap-software/200102/msg00345.html: "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..)"
15 years ago we weren't sick of answering questions about things that had already existed and been documented for 15 years.
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 ...
We want to gain useful allies - those who prove themselves capable of reading. The lazy or ignorant can take a hike. Oracle would love to have their business.
All knowledge transfer here is happening through the written word. It makes no difference how carefully or exhaustively we write docs if people are too lazy to read it. 10 years ago the complaint was "the documentation is so incomplete it's inadequate." We appointed a Documentation Lead (Gavin) and spent a huge investment of time in consolidating and clarifying docs. Now we get "there's too much documentation." It's a no-win situation with those people, they will always have something to complain about. Meanwhile, the majority of the user base has been contentedly getting their work done and moving on silently.
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 ...
Have done all of that. And it is my policy now to only post links to previous instances of a question/answer, rather than answer anew.
openldap-technical@openldap.org
-
Daniel Howard -
Howard Chu