[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: Documentation

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. 

--
  -- Howard Chu
  CTO, Symas Corp.           http://www.symas.com
  Director, Highland Sun     http://highlandsun.com/hyc/
  Chief Architect, OpenLDAP  http://www.openldap.org/project/