I recently enabled LDAPS authentication for our Drupal site so users can log in with their Active Directory credentials. It wasn’t the most straightforward setup (both from a Drupal standpoint and a networking standpoint, since our website is hosted off-campus) so I wanted to write up documentation for internal reference purposes and a blog post about my LDAP hurdles as they relate to Drupal for anyone else running into the same problems.
I’ve never been one for writing excessive documentation. Usually a couple of notes in comments is all that’s really required to explain why you’re doing something, but when you’re trying to explain all the prerequisites that built up to that point and the logic behind the decision you can easily end up with pages upon pages of rambling notes. How do you organize things like that without going totally overboard?
Typically I also run into a dilema when I’m trying to decide how much to “dumb-down” the documentation. Obviously I’m trying to explain a point to someone who does not have the benefit of my experiences to understand it, so how far back do I go to make sure they get the point?
The adage that if you asked the question you should document the answer is a good guideline, but again that leaves you with many rambling and semi-related topics in a FAQ-style document. That’s great for troubleshooting but not at all ideal for people trying to follow a step-by-step guide and get up and running quickly.
In the end I decided to write a paragraph-long “Abstract” section that outlined the goal and then add a paragraph that explained the two distinct parts – the networking portion and then the PHP and Drupal configuration. I used the default Heading styles in Word 2007 and made each of these parts a new H2 with their respective intro (aka “Abstract”) paragraphs explaining what they did at a high level, followed by sequentially increasing levels of Header tags as I worked my way down through the nitty gritty details.
All told I think I ended up with 5 pages and it took me several hours of writing, editing, reviewing, and expanding sections that needed clarification. If I never had to document anything like that again I would be deliriously happy.
For anyone wondering, I’m still working on the Drupal w/ LDAPS blog post, it’s just a long process.
