First things first: I’ve you’ve ever looked at Acquia’s documentation, read this post and take the survey. You’re welcome, jam. 😉
Now, a confession: I went to the Drupal.org documentation sprint at DrupalCon. And I tried to be useful, really I did. But I found myself frustrated, unable to really engage in it, and left mid-day feeling horribly guilty. Why? I think there were two causes:
- The task is so immense. Drupal.org’s documentation has grown like topsy, and now useful information is dispersed throughout several unconnected areas. The search function is really all that brings them together.
- Quality varies wildly. The biggest sin is, as usual, too much writing. As I often say, writing is easy; editing is hard. Brevity is the soul of wit. Your mama wears combat boots. And so forth.
I wrestled with the task facing doc team lead Addison Berry: What would I do in her place? My answer surprised me: I’d burn it all down and start again.
I’m reminded of the real-estate markets of Detroit, Cleveland, and Buffalo. In those cities there are blocks full of houses that are worth less than nothing: They’re too dilapidated to restore, and the cost to demolish them (about $8,000) is greater than the land’s value. And ashes are cheaper to truck away than lumber, even if the burning dumps toxins in the soil.
What “city blocks” on Drupal.org are like that?
Such arson is unlikely to happen on Drupal.org. For one thing, it’s discouraging to sweat out a long document, and then discover that it’s disappeared. How many people would stop contributing documentation as a result? How would the community’s soil be poisoned?
I’d still recommend cutting mercilessly. I believe at least 75% of the words on Drupal.org could and should be lost. But who would do the cutting? It’s tough work, and without glory. Converting Drupal.org’s documentation into a wiki(-like) format might help “crowdsource” the task. Or maybe not. Nobody likes to cut. Editing is hard.
Which leads us back to Acquia.
Acquia is a “third-party documentation provider”, like the Lullabots and GotDrupal and DrupalTherapy and many others… and me. It’s tempting to say that we thrive because of the weaknesses in Drupal.org — that is, that they create a vacuum that we fill — but it’s not really true. After all, Apple’s documentation is pretty good, but that supports outside writers rather than cannabilizing their work. In a healthy project, there’s always a new audience to reach.
But we outside doc providers have an advantage over Drupal.org: a clear field. Arson is unnecessary, and will put no toxins in the soil. Each building we create on these virgin plots can reflect a different architecture, each fitting a distinct family of users.
That’s why I think it’s great that the Lullabots’ CCK and Views videos will be available alongside my own: Theirs reach a certain audience, while mine will reach a different audience. And both of us can only do what we do because of the base provided by Drupal.org’s documentation. Together — we outside doc providers and Drupal.org — we all grow the Drupalsphere.
36 replies on “The problem with Drupal documentation”
I agree, more structure required
I agree.
For one of the patches for D7 I made I was asked to document the API change. I spent 5 minutes looking for the correct page until I simply asked on IRC were it was.
Things like that should be better organized. There is a lot of useful documentation available but it’s simply not organized. I would shut down documentation for a week and sort it out, place everything in simple and correct categories. If you click on 8 sub-links in the menu you end up with 5 different menus in which you really get lost.
talk about writing too
talk about writing too much… 🙂
Ooo, burn!
Good one. 🙂
Slash and burn
I could live with a little verbosity if (a) I could only find the information I was looking for and (b) the information I was looking for was found within the context of other content that was relevant to the issue I was exploring. So for me, verbosity is troublesome but the really serious problem with Drupal documentation is the lack of structure.
I suppose that back in the early days, when there were few users and little content, it was perfectly fine (or at least expedient) to toss the handful of pages into a couple of generic buckets with vague headings like “Howtos” and “Getting Started” but over time, these buckets have swollen to mammoth sizes and now encompass a teeming swirling mass of topics all jumbled up together in no particular order and no sensible grouping. Some of the guidebooks are better than others. The developers guide and theming guide are not so bad but from structural point of view Getting Started and Beyond the Basics are nothing but a disaster. I don’t think the content needs to be burned to the ground, but the current structure, such as it is, should be completely ripped out and replaced.
Basically in agreement
Hi, Lee. I think we’re basically in agreement, actually. My *instinct* is to want to slash and burn, but in reality that would be overkill. And I, too, think that structural problems are bigger than wordiness. But I was overly wordy about the latter. 😉
The real problem with Drupal’s documentation…
…is that people who see problems that can be fixed and have the requisite skills to do something about it fail to do so. Are you willing to buck the trend? There’s an edit tab on every page…
True and true
Hey, webchick — I’m glad you commented here. Your response actually proves my point, which is that some people believe that structural issues can be solved with edits. IMHO they can’t.
Having said that, I also realize that I’m irresponsible in standing on the sidelines and criticizing. If I really wanted to make a change, I should jump in and do it — that’s the beauty of the open-source process, right?
But some things don’t scale: Nine women together can’t produce a baby in one month. 🙂 This fundamental reorganization is one of them.
I’m not angling for the job, and I give Addison a hell of a lot of credit for taking on the tasks she’s identified. (Seriously, I hope that nobody takes this as a criticism of her work or dedication, both of which are AWESOME.) She’s implementing important, helpful incremental change, and a lot of it. However, I believe that the project is running up against a wall because of the documentation store’s structural issues. And nothing but a dictator’s fiat will knock that wall down.
Having said all this, I sure hope I’m wrong. I’d love to see the current path of change lead to something beautiful, even if it takes a year or two. But I wanted to voice my doubts.
I dunno…
I see problems that can be fixed, I have the requisite skills to do something about it, and I even use that edit tab… but the changes I’m able to make are but a drop of water in the comprehensive ocean of what’s wrong with the drupal.org handbooks. The main problems are structural, and you can’t fix structural problems a page at a time. That’s why we need someone like add1sun, with the resources (yay!) and vision to decide on broad-based organizational changes. I think she’ll have plenty of worker bees willing to hit that edit tab whenever she says the word.
I agree – a lot to fall on
I agree – a lot to fall on add1sun’s shoulders, but a strategic vision is needed before the content is revised
That’s not it
I could fix the structure in a couple of days. I’ve got the skills and experience and I would be totally willing to do it. It would actually be a fun job. But we’re talking major surgery here – head transplants, reducing the number of legs from five to maybe two, moving the position of the eyes and ears – and clearly this requires some kind of prior engagement and buy-in from the stakeholders. It’s not something that I can just jump into on a whim and mold it in my own image. Restructuring within a handbook I’ve done (theming guide and developer guide etc) but ripping out several major structures completely and creating new guides is a different story.
what would help restructure
concur (how was that for succinct). One does not “jump in” as an individual to uni-laterally make huge structural changes to a community site.
I’ve noticed changes since the last time i tried to install/learn/use Drupal — someone at least has been putting many pages into book outlines, but it seems without a comprehensive overview.
What would help so much when/if restructuring would be an overall list of all pages that are “documentation”. I’m used to wiki namespaces, where you will find the manual inside the Manual: or Help: space. There seems to be no way to isolate documentation pages on drupal.org, and a way to search ONLY within the docs (to this day I cannot find a link for the “Advanced Search” that one is advised to use!!)
Wishing for a namespace. Maybe docs.drupal.org perhaps would be the equivalent of http://www.mywiki.com/Documentation: …
kazar
But if the online documentation was great…
If online reference was really that great, then the burgeoning market for reference/tutorial books would die. In a way, the books that have appeared in the past year have allowed me to learn far more about overall Drupal concepts, than stumbling through the online resources. And this separates Drupal from many other OS projects, especially as the core codebase is remaining pretty stable for almost 2 years. I’d also like to think that some of the experienced Drupal developers are actually getting financial payback for all work they do, by publishing books.
I’ve been working in Drupal for about 9 months now, and still feel reluctant to edit any online documents partly through lack of confidence, and also because I feel a little lost once in the documentation world (is there duplication? is there a great article already in the discussion forums? etc). Apart from my first ever D6 install, I don’t think I’ve since navigated through the docs from the d.o homepage.
Slash and burn? Maybe a little too drastic – the current documentation is certainly not worthless. After all, we can still find what we want (eventually) by persistence with Google.
Some disagreement
Hey, Snorkers — thanks for writing. I disagree with two of your points:
If online reference was really that great, then the burgeoning market for reference/tutorial books would die.
I don’t think that’s true. I guess the best way to show that would be to point to a project with *excellent* documentation, and then show that there’s still a market for outside books etc. How about Twitter? There are books about that, although it’s hard to imagine that anything *needs* documentation there. Yet there it is. Lynda.com just released its Twitter Essential Training course, and as Lynda said in her latest newsletter:
Secondly, you write:
I’d also like to think that some of the experienced Drupal developers are actually getting financial payback for all work they do, by publishing books.
But the money’s not going to them! It’s going to schmucks like me. Writing and developing are very different skills, and rare is the person who has the skills and time to dedicate to both. Consider: Using Drupal took six people a year to write, as far as I can tell. Splitting one royalty check six ways is no way to make a living. That’s because they all have other jobs: They’re developers and themers and such.
On the other hand, I wrote Save My Home in a month, and when my Drupal book for Peachpit is done I’m guessing it’ll have taken about two months of solid work (spread over a year). Practice makes presto, or something. 🙂
Lack of confidence
I agree with your comment about lack of confidence – I’ve been using Drupal for close to three years, but my experience has intensified in the last 12 months. All the same, I’d be petrified to amend a Drupal handbook page because a) I wouldn’t want to put on information that was inaccurate, and b) I wouldn’t want to get slapped down by a more experienced Drupaller.
For that reason, I write my notes and share them on my own site. That way, I know I’m reporting what’s worked for me and if somebody else feels the need to correct that, then they can leave a comment.
@Tom – I think it’s alright to state your opinion, even if you *are* standing on the sidelines. I have a ton of great ideas for how Drupal can be improved, but not the slightest idea or expertise to execute them. But it’s all valuable feedback for the developers. That’s my position anyway!
I have ideas, and expertise, but…
Hey, Gerard — thanks for your comment. I *do* hesitate to say “such-and-such is wrong” when I’m not willing to do the hard work to fix it, if only because that’s endemic in such a community. It discourages those who actually do the work, and that’s the *last* thing I’d want to do!
Agree so strongly there are no words
I started using Drupal a year ago, and I HATE the documentation with a passion. Personally, I think it is a bigger barrier to Drupal success than the UX issues that are being addressed.
Yes, we can use the edit tab, which is akin to arranging deck chairs. The problem is not so much in editing individual pages, it is structure, findability, logical connections, relevance.
I would love to help make it better, and I see no way to do that without a slash and burn. One of the biggest issues is just how mashed up everything is together. I get particularly defeated by D5 content – I have never used D5, and don’t want to see that documentation. It could be relevant to what I am trying to do in D6, but I don’t know if it is, and it usually appears it isn’t. Meanwhile, it is so dominant I can’t find what I really need.
I think there are models of how to do this well.
Why not create a new, logical structure – which separates documentation by version, by type, etc and create an all hands on deck effort to move the relevant existing stuff to a new structure? That is an effort I could get behind.
Good for you for speaking out.
And yes, the four books I have purchased have all been many times more helpful than the docs, sad but true.
I agree completely – it’s a barrier to entry for many
In the process of researching different CMS I often came across people who had abandoned Drupal due to a perception that the community is not helpful. Often it would turn out that what they really meant was that the documentation wass not helpful, and they could not understand why it was allowed to be so oblique.
I’m now sufficiently far down the Drupal development line that the initial frustrations are over but I still remember the experience of trying to find out how to do things. In general, I’ve found sites other than drupal.org more useful resources regarding how to do certain things, than drupal.org itself.
I think wikipedia is a great model collaborative documentation and the Drupal documentation pages should aim to follow a similar model: E.g.
* Do not restrict who can edit pages, in favour of making it easier to contribute *
For example: I really cannot be bothered to go through the process of joining a drupal documentation group. The only people who will get around to doing that are the relatively small number of people who are sufficiently dedicated to go “on a mission” to improve the documentation. The reason wikipedia works is because *anybody* can contribute, and then the dedicated peeps concentrate more on quality control. And as is plain to see, it *does* work.
* Rely on links in the content and the search function to navigate *
The drupal documentation site attempts to use the left hand navigation for, well .. navigation. This really does not work. I basically ignore it and rely upon search.
* Use the right tool for the job *
Drupal is great for setting up a content managed website. It is not so great for creating documentation. I would actually propose using something like MediaWiki to do this job. Accept that Drupal is not and should not be trying to be all things to all people.
And agree about the scorched-earth policy
I should add that I don’t envy the job of those who have to sort out the documentation.
It is a mammoth task.
Nonetheless, I agree that if it were my job I would essentialy scrap the whole documentation area and start again from scratch.
Indeed!
Hi Tom, et al.
Thanks for bringing this up and to people leaving comments. I don’t have time to do an extensive response to the whole thread, but did want to chime in with two thoughts:
1) Man, do I feel your pain. I agree that the edit tab is not the issue, but we have some really big over-arching madness that needs to be dealt with.
2) We are working on it, really! Shortly after Drupalcon we had a very focused sprint to hammer on the big nasties and since then there has been a small pool of people helping me pull all of the brainstorming together into something the community can attack in an organized manner. I know I’ve been slow on getting things together, but I’m tying up a few things and plan to really get things moving within the next two weeks (so perfect timing!), hopefully before I hit the road for three doc sprints in Scandinavia at the end of the month. Top of the list is an IA working group led by Becca Scollan (from U of B usability sprint fame). So, sharpen those knives because there is plenty of work coming down the pike. There will be a front page post on Drupal.org as well as lots of Drupal Planet chatter once we get things rolling.
I figured you were working on it. 🙂
Hey, Addison! Thanks so much for responding, and I hope you don’t mind me raising this here. I considered chatting with you first, but I was looking for community response as much as personal satisfaction.
There are two centers to the documentation problem IMHO:
1) Poor tools/input. Drupal’s “Book” format just isn’t right for this sort of application, for several reasons (which I’m sure you already know).
2) Poor delivery/output. OTOH, I remember you saying something about moving some documentation to Advanced Help, which I think is an excellent idea.
Both issues require architectural changes, which is why edits don’t help. I *do* believe in your ability and drive to solve them; I hope you’ll be willing to “break a few eggs” to make this omelette.
[That expression is attributed to Robespierre, BTW, who allegedly used it to justify murder in the name of the revolution. So if you make a few enemies along the way, feel noble by comparison. 😉 ]
Recommendations of better software?
What would you, or anyone else, recommend using for documentation handling? Or, what current software(s) would be cool to copy from or maybe integrate?
Good question.
That’s actually a very good question. I think a Wiki is incrementally better, if only because it has much better versioning.
I was thinking about this earlier today, and believe that a better documentation system is possible in Drupal itself, but it would require some serious design work. For example: Create a “How to” content type that’s based around illustrated step-by-step instructions. Limit the size of each step to a certain (small!) number of characters, and require each step to be accompanied by an illustration. Require tags. And so forth.
I just started working on the “Drupal 7: Visual QuickStart Guide” book for Peachpit, and the level of formality in its structure is *astonishing*. Some of that discipline on the micro level would do well on Drupal.org; I think it could lead to greater discipline on the macro level.
Progress – Doc maintainers – Seeing forest amongst trees
Thanks for this, Addi. This thread already feels like consensus-progress (so important in OSS projects).
Glad you agree that an open edit tab isn’t enough, too. A semi-empowered user in a sort-of democracy of other semi-empowered users cannot make the fundamental changes we all (seem to) agree we need. Managing and updating documentation is not quite like managing code. To get the documentation in a better state, we need a strong editor or two who are the documentation equivalent to branch maintainers. This very small pool of people should have the accepted “right” – or better, mandate – to (re)define structures; remove entire nodes, putting their essential content into other nodes; move around and redefine chapters, sections, and so on. Major forestry.
I look forward to doing my part!
Thanks for the shout out, Tom!
I think you hit several nails on the head here; the main one being that 3rd party documentation providers have the freedom to address their work to specific audiences for specific purposes while adding value to the Drupal experience and biosphere for everyone. The more people who distill down their Drupal knowledge and experience into digestible pieces, the better!
During my first attempts at installing and configuring Drupal (4.7), the “signal-to-noise ratio” for beginning users on drupal.org was overwhelming. Not knowing all the jargon or the right keywords to search for, I waded through pages and pages of gnarly, hard-core stuff, hoping to stumble on whatever simple configuration information I was hunting for. I suspect the experience remains daunting for newbies, although the value of drupal.org has grown for me with my ability to understand and appreciate the incredible depth and value of the information available there.
In Acquia’s case, we are trying to make Drupal easily accessible and attractive to as many people as possible, and have a lot of documentation aimed at getting up and running quickly and easily. As part of the same goal, we also have a number of ways to make installing Drupal easier than ever like the Drupal stack installer for Windows and Mac (and soon Linux!) and the full Acquia Drupal distribution in a public SVN repository.
And yes, as I mentioned, we really appreciate the help provided by anyone who helps us out by taking this very quick survey.
Problems and solutions
I’m excited to see that people are inspired by documentation enough to rant about. Now I look forward to seeing that energy flipped around and made into a wish list and a vision for what documentation could look like.
My grandpappy used to have a saying, “If you’re not part of the solution, you’re part of the problem.” It’s really easy to moan about all the things that are wrong. But if we all do ONE thing different and all pitch in our ONE commitment to a solution, we’ll be 200,000 steps closer to a system that works for each of us. Good writing is hard work, good editing is hard work, and good visions are hard to come by.
Blog your vision for success, get excited about it and others will join you…but perhaps most importantly you’ll see how many more people there are who are already working on these tough problems. Roll up your sleeves and start blogging about the ONE next step you’ll take to help Drupal be even more awesome!
And if you’re on IRC drop by the #drupal-docs and see some of the things people are already engaged in, excited about, and working on!
It’s easy to throw stones at
It’s easy to throw stones at the house than to build the house.
My answer to this: if you got time to rant, you’ve got time to make edits!
As with any big project, it is daunting to think of the size and scope.
Scratch your own itch. In other words: It’s better to claim a small part, make it meaningful to you and own it.
Let others worry about the big picture.. read: add1sun.
Many hands make light work.
burned it down twice
I’ve burned down Drupal.org’s documentation twice. Djun Kim(purejin) did it once before me. I view it as a task that needs to be done every 18 months or so.
1. Survey.
2. Decide on your vision (this is where you talk to people)
3. Present the plan / outline
4. Get buy in. This is not as hard as some people think IF your plan answers their concerns.
5. Schedule announce
6. Get some people to be available towards the end to review and fine tune.
7. Schedule your time. Edit / organize / prune. (estimate a minimum of 40-60 hours of time for this part alone)
8. Post completion.
Drupal.org’s audience evolves as the technology evolves. As a result this re-org is useful. After each re-org it helped solve the problems people had in the forums or in IRC with finding content.
With expansion comes contribution and change and growth. After a time, it is time to prune. I was ruthless with outdated content. If it hadn’t been updated and was no longer on a supported version of Drupal, it was gone (gone as in deleted). This approach really riled up many people and I got nasty messages. There is ‘religious belief’ that links are forever, they are not. The current drive is to ‘archive’ outdated content in it’s own section. I have always believe that that polluted search results, if a ‘how to’ is not updated in 3 versions, it’s not that important.
I do believe I mentioned this approach a time or two to various people who wanted to re-organize / edit books and content.
Drupal is not static. Drupal.org is not static. There are many audiences for information and many different methods to find / discover it. How to address the interwoven nature of drupal code /configuration / content management is and will remain a moving target.
I think it’s great that Acquia has your stamp of approval. I think it’s great they are paying people to write documentation. Certainly there is more control when you pay people or gain revenue from such then from hundreds of random volunteers.
Many have thought they knew better. They went off and built their mouse trap. I don’t know, I got tired of it and stepped aside.
Steven Peck (sepeck)
Excellent advice from the past
Steven:
Thanks so much for posting your comment here. I’m going to point Addi to it.
(For those who don’t know: Steven was the Documentation Team Leader, and has had a Drupal.org account for over five and a half years — here are the details.)
Mention of this thread on the DrupalEasy podcast
Just a quick note to mention that this thread was discussed on the DrupalEasy podcast, Episode 8, at around 12:30. One quote stood out to me:
For the record: I voted for Dukakis in ’88. 😉
Another problem with documentation…
People who want to take the hard work that others have done (even though it should all be burned to the ground, of course) and circumvent the license by which that work was contributed for their own gains:
tgeller: Does anyone here understand the Creative Commons License well? I want to use a graphic from the drupal.org handbooks in a corporate document, and am not sure whether that means (a) I just have to mention that it's under CCL in the credit, or (b) I have to include some big disclaimer text elsewhere. I also want to be sure it doesn't "infect" the rest of the document, which is traditionally copyrighted. Do you know, webchick?
webchick: tgeller, AFAIK the license links to the license text, no?
webchick: so read it, and do what it says. ;)
tgeller: webchick: It seems to say that it'll infect the resulting work... just hoping that someone can prove to me that it won't. ;)
webchick: tgeller, Hm. So you want someone to help you use a document someone created with their own volunteer time for you to make some money, and you want us to help you find a workaround? ;)
webchick: That doesn't seem like something we'd want to do. :P
tgeller: webchick -- I claim ignorance! That's my excuse, anyway.
This is absolutely offensive, and I sincerely hope someone stumbles across this and it gives them pause for sending any money your way.
The source of the confusion
Webchick:
Of course I’m shocked and saddened to see this turn into a dustup. I am not, have not ever, and never will attempt to “work around” a license, and that’s not the case here. My sin here is laziness, not deviousness. Here’s what happened on my side.
I’m on the phone with someone who wants to use a graphic from Drupal.org in some documentation. I say, “I don’t know if that’s possible… let me find out”. Licenses aren’t my specialty, and I’ve misunderstood non-traditional licenses in the past. I wanted to make sure I got it right, so I jumped on the #drupal channel of IRC to get the answer “from the horse’s mouth”.
While logging in, I realized that I should check the source (duh), so I go to Drupal.org and poke around for the license (which could be easier to find, but whatever). I see that it’s under some sort of Creative Commons license, and pose my question.
You cut out (or missed) part of our conversation. You write:
webchick: tgeller, AFAIK the license links to the license text, no?
webchick: so read it, and do what it says. 😉
I wrote something like, “Oh, duh! Of course”, went to read it, saw that we couldn’t use the graphic as we wanted, said so, and thanked you. (I didn’t save the chat, but encourage anyone who knows how such things work to read through the logs. Is that possible? I’d like to do that.)
I can see how the last line you quoted seems like I mean, “Ha ha, I’m going to pretend I didn’t hear you and circumvent the license!” What I actually meant was, “I was stupid not to think of following the link to the license text from Drupal.org”. This all happened within a few seconds, mind you, while we were both distracted by other things.
I’ll leave this discussion up unless you tell me otherwise. I’m sorry that my glibness led to a misunderstanding, and hope that it doesn’t affect our relationship, however slight it is.
Posted in IRC
I wrote this after posting the above, to clear the air to all who might have been witness to the above exchange.
Problem/Solution
emmajane wrote: “My grandpappy used to have a saying, “If you’re not part of the solution, you’re part of the problem.”
Brand new to Drupal, I’ve found videos to be the best documentation of all, and Geller’s Lynda.com videos to be the best “solution” to the problem: paced so as not to insult your intelligence but free of geek-speak.
By the way, there are great ‘Academic T-Shirts’ that state: “If you’re not part of the solution, you’re part of the precipitate.”
http://www.zazzle.com/precipitate+tshirts
More structure required
[NOTE: This comment was posted by eFeS (http://infoblog.tatrai.hu/), and I accidentally deleted it. Sorry! Here it is. eFeS, if you’d care to repost it under your name, I’ll delete this version. –Tom]
I’ve tried Typo3, Joomla!, WordPress – and now I’m with Drupal. The doucmentation of Typo3 was a mess, Joomla! is a little bit better. I think, WordPress is the absulote winner.
Look at the codex pages at http://codex.wordpress.org/Main_Page , or the function reference at http://codex.wordpress.org/Function_Reference It is very clean, well organized, easy to handle even at first sight. I would recommend something for Drupal too. To find anything at http://api.drupal.org – even if you’re a beginner, like me… – is a nightmare…
Excellent concept and technology and badly organized documentation, in which very hard to find anything related. I think, that’s the truth about Drupal nowadays.
Changing the documentaiton every year
I suspect that part of the problem is that Drupal.org has a policy of putting out a new release every year, and changing the API & GUI at every release. So all the documentation should be re-written every year. For example, the arrangement of the Administration menu changes every year.
It takes a year to write, check, edit, and publish a book, so the “Dummy’s Guide to Drupal” would be obsolete the day it hit the bookstores. Even the online documentation does not get fixed.
Amazon.com is selling “The C Programming Language” by Kernighan and Ritchie, (2nd Edition, April 1, 1988). That’s a 23 year old book, and still valuable today. A 3 year old book on Drupal would be useless.
That does make it harder…
As you probably know, Drupal’s leaders follow a philosophy that “the drop is always moving” — that is, they don’t make much attempt to keep things consistent between versions. That definitely does make things harder, but perhaps we disagree about just *how much* harder. All software documentation needs revision when there’s an update: Joomla 1.5 docs will mislead users of Joomla 1.6, too.
Regarding books: We planned my book to come out contemporaneously with Drupal 7, so it certainly isn’t “obsolete” now! The problems we had with it weren’t because so much changed between versions — it was written from scratch to begin with. The problems occurred because Drupal’s leadership utterly disregarded the deadlines they themselves had set, making fundamental interface changes long after the “UI freeze”. That’s another matter, which I’ve discussed elsewhere.