The redesign has been doing lots of great stuff, rethinking how we approach Drupal.org. We should take this opportunity to really think about how we present documentation on the site. There has been a lot of talk and there are lots of little nits of annoyance in addition to the larger complaint of organization with regard to the handbooks. I wanted to try to gather up at least some of the larger things for us to consider and continue the discussion so that we can focus on specific changes while we have the services of MBD available to us. MBD has put up a new prototype iteration that is now beginning to address the documentation section. This is the perfect time for us to organize our thoughts and give feedback to craft a better solution.
There is an older discussion that was started earlier this year about a Drupal Knowledge Base, which was a doc-specific spin off of ideas from an original high level redesign post. Incorporating some of the thoughts from that, as well as other discussions on the mailing list and in the issue queues, here is a (I'm sure incomplete) summary of "big" things I think we should address during this redesign. I encourage everyone to not just talk about this, but to actually make some quick wireframes to help everyone see it.
-
Overall architecture of the handbooks:
Everyone has different ways they expect to find the information they need. The documentation comprises of several different "books." What content belongs in which book is one issue, but also pulling back a bit and looking at what we are using as top-level books to compartmentalize our content needs to be looked at. Do we have too many separate books? Not enough? Should we be grouping things together differently? In particular a book like "Beyond the basics" is really more of just a catchall bin and rather vague. -
Versions
Much of Drupal's documentation is written to the version of Drupal software (and we currently mark the version(s) with a vocabulary). Many pages apply to more than one version, some pages apply to all or no versions. It would be great to be able to look at the Drupal 5 version of the handbook and cut out the clutter and noise of other versions. It is a lot harder than it sounds. Much of this is a technical problem to solve but what would an ideal, or even achievable ;-), design for this look like? What would we even shoot for >? Something like the API version tabs? What do we do about pages that need no version at all? This is a really hard problem but if we can find a solution that even moves us in that direction, it could be a huge boost to make it easier for people to find the info they need. -
Taxonomy/Tagging
We currently have two vocabularies for handbook pages: Drupal version and a new page status. These act as "flags" but do not really help us organize our content, nor make any easier to find what you need. How can we think about using taxonomy to improve this? People want to find info in different ways at different times. Tagging our content to give people more "meta" info could help people track down and group the information they need. Again, how does this look? How would this most help us? -
Videos
We currently have a video section of the handbooks (under Beyond the basics) but as video becomes more and more popular, I think we need to look at how to really effectively address these informational videos. Where should they be? How best to organize them? How do we make them easy to find and view while also linking them up with the appropriate written parts of the handbook? There is a thread on video ideas that can be looked where some of these things are discussed. We should also note that the Dojo will be reviving their external site as a simple way to host videos. I think we should work with and think about this as a prototype for what we can do within the Drupal.org handbooks for videos.
Comments
High Level Structure
It would be hard to cover everything in one post, but here's what I'm thinking from a high level view.
It would be very helpful to the documentation if we approached Drupal as an enterprise level application. First of all, because it actually is an enterprise application, but mostly because thinking in those terms would tremendously clarify how the documentation should be structured.
What I mean is that the documentation for an enterprise application is generally split up according to the audience. We're part way there in that we do have a developer guide and a theming guide and those books have clear, and obvious, audiences.
Things get terribly murky and confused, though, with "Getting Started" and "Beyond the Basics" which seem, both from the titles and the content, to be aimed at anyone, everyone or maybe noone in particular.
I can see the need for at least five "books" which are aimed at specific roles in the organization (note that even if I'm a one-man shop, this kind of division is still helpful because it automatically steers me to the information that's most relevant to the hat I'm currently wearing)
Here's one way of breaking things down:
Versions
When documentation is written in an application like FrameMaker, it's typical to use conditional text to mark the content that is specific to a particular version. Conditional text can be a little tricky when you're marking little bits like individual steps in a procedure, but is very easy and robust when applied to big chunks like chapters.
It seems to me that by tagging pages with Drupal versions, we've already got the basis for doing sole-sourced books using the tags as the equivalent of conditional text. In other words, instead of creating separate installation guides for D5, 6 and 7 we only need to create one installation guide and make sure that the pages are tagged appropriately. The user will see separate links for "Drupal 5 Installation Guide" and "Drupal 6 Installation Guide" but when they click on the Drupal 5 link they actually get the common installation guide, pages that are only tagged as "Drupal 6" are just filtered out. Documentation writers will of course still be able to view all the content in the common installation guide.
This would the books much more usable, maintainable and consistent.
Maintaining structure
Yeah, we do have the tags, but we need a bit of code to make them useful. The biggest problem that we need to address in code is a way to view all of the D6 handbook pages in the same book hierarchy. I've been playing around with Revision tags module to see if that is a direction we could go in, but it's not quite right yet. I think we can write up the code but having a clear idea of how to select versions would be good. So like would we have a version filter select list like the module page or tabs like API or should we have a top-level nav item to, for example, "Drupal 5 handbook"?
I'm also not sure what would happen to display of things when a parent item isn't marked for a book, what does that do to the child pages? For instance, if I have:
Widgets
- widget a
- widget b
but for whatever reason "Widgets" is only marked for 5 and the children are marked for 6. What does that do the book structure? That's not so bad with this small example but it could make things very messy. I'm just tossing things out without thinking through them very thoroughly but these are the things that I wonder about. Basically we aren't just trying to filter the pages, but we also need to keep the structure intact.
Lullabot loves you
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans
Learn Drupal online at Drupalize.me
Some Ideas
First of all great summary. I have to read it again to be fully on screen. For beginning some Ideas:
To simplify our job of maintaining the Handbooks in a well structured way and we need more live info for evaluating documents and also issue and comments to put first on duty. I have post this issue about possibly additions to Issue Information. I just am learning with my active collaboration on drupal.org that without a background on Project Management Work, like this is in my eyes what the main drupal.org staff is doing here, that is not easy to step in and help out.
Yes, I and many others get a lot of experiences of acting on Drupal.org as active members and do acquire important knowledge they can then apply to their own projects as my main task is. I just feel that something is missing here:
I don't see a clear structure of managing outdated content: Old Comments, old Issue, Issue without answer and categorization, expiring roles for content and so on. This leads to an extreme chaos and visitors will soon or later step in it and who cares will post and comment. So I think that this demon circle will always repeat it's self on regular base in time.
Who have an idea on my memberships story are sure aware of many issue I have made about those statements. So I will not list here issue links and comment refers.
Thanks to all the Staff for the great work they are doing for Drupal and Drupal's Folk.
Taxonomy and videos
I'd love to see us use the Faceted Search module in conjunction with taxonomy. For people who enter the documentation through a search, this would provide powerful insight into the structure of the docs and a great navigation tool for making their search broader or narrower.
Some of the taxonomies I'd like to see are:
content type: tutorial, procedural, conceptual, video (one tag only per article)
content: Apache, CCK, Views, blocks, menus etc (multiple tags permitted)
Re. video I'd like to see it displayed using the Views module so that the content could be sortable and filterable on different fields. But since we're using tags, we don't have to stop there. We can also have relevant video content integrated into each book so that if you're browsing the Administration guide, you'll see that there's a section which has all the videos on administration topics. There's no reason to force people to navigate to a separate video section where they'd have to drill down through a bunch of unrelated content, when we could have everything matching to their current interest, pulled together in one nice bundle.
I'm really excited that we're looking at these things. There's tons of excellent content in the Drupal documentation. If we can make it more browseable and findable it could be really amazing.
Agreed
One of the main things I want to do with videos, besides just organizing a video section that is easier to use, is to also integrate them right into the rest of the book.
One thing I was chewing on re: tagging and such is would it make sense to have some structured vocabs for major pieces we know we want to organize by and then also allow community freetagging as well? I tend to be a dubious of freetagging in that it can get quite messy very quickly, but if used well, it can be a huge help. Dunno, what do people think about that?
Lullabot loves you
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans
Learn Drupal online at Drupalize.me
structured vocabularies vs. folksonomies/free tagging
I have to projects of my own that I've been very busy working with with regards to the information architecture and taxonomy. One little technique that sort of developed out of a desire to be both well organized and readily findable by both users and search engines is a process where we're creating controlled vocabularies, then going off to an online search volume database, and figuring out which term or keyword is most likely to be used by a user (or searched by on an search engine and then get a hit and traffic to our site.) For example one person might search for "pics," another "images," and still another "photos," so if you look at search volume, you can try to choose a term currently being used in searches by the most people. I use the one at http://tools.seobook.com/keyword-tools/seobook/index.php but there are a number of them online, this one is simple, free and based on WordTracker's database, so it's reliable.
Okay so all that is context for my opinion: free tagging is really handy for certain things but when it comes to finding precisely the right documentation for a problem, controlling the vocabulary seems like it would be a better choice for us, as the more that different things are tagged with overlapping (competing) terms on such a huge site as drupal.org, I think the the single item people are most likely to be looking for will become diluted by the volume. I'm pretty new to IA stuff in general, so I could be completely wrong, but from what I've learned so far that seems right to me. This would probably be a great thing to bounce off of Leisa, because she does this full time.
-=- christopher
-=- christopher
logistics
I haven't been involved in Drupal documentation in quite a while, but if you think of documentation construction and maintenance on drupal.org as having a limited set of resources, isn't free tagging vs structured vocabulary more of a question of logistics? In other words, is it feasible that an effective controlled vocabulary can be created, implemented, and maintained over time? Free tagging is undoubtedly messier and perhaps less effective, but as a more participatory method, it's a comprise which draws more on the larger audience of users to make a quick contribution over the regular, dedicated maintenance which would be required of a structured vocabulary.
There are a lot of
There are a lot of interesting modules that help authors choose the right tag even when using free tagging. We should probably use one. For example (well known module authors):
documentation type
"Documentation type" would likely be a better vocabulary type than "content type" given (a) it's more precise in its description and (b) "content type" is already used in Drupal terminology in the Drupal admin menu.
Does it have to be a book type?
I am not entirely convinced to the whole book Idea - while this structure is very good for paper publications it doesn't work well for the online knowledge base
To sum up - if you're just about to read about the basics or one of the guides the book format works pretty well, but once you need some specific information you're stuck neck-deep in an ocean of shit. If the information is on some more advanced subject and you need to know in detail how a specific part of Drupal (or a 3rd party module) works then not only you're stuck in the ocean but a tide is coming.
books
I think Etanol has a good point about the books. I'd guess that most traffic to individual handbook pages is via google and drupal.org search. I've helped write documentation here and there in different sections, but it always takes me a while to find it if I try to navigate through the book structure.
So.. the idea of having a strict structure for the introductory sections sounds great. For something like module documentation, things are far, far too levels deep in the structure - really we should try to avoid anything more than 3 clicks deep from the front page. For documentation which is related to specific modules, I'd like to see a 'modules' vocabulary, then maybe tag clouds to navigate this (so that modules with the most pages written about them get promoted higher in the lists). In the 'projects as organic groups' thread, there's been proposals to have a 'documentation' tab on module pages since maintainers would be able to use panels to structure their pages, some way of integrating content in either direction (since this will be two different subdomains) would be great.
I like the idea of API style tabs for the version tagging, that sounds like a decent plan. Either that or something like how language negotiation works in 6.x - so you choose a version and this is stored in the session and filters all subsequent requests.
Regarding tag clouds
What is the general disposition here regarding implementing a tiny tag cloud block to perhaps pop some words into people's heads. (I know it was on the list a few weeks ago)
How about having featured documentation and guides selected by users?
The problem is not books vs something else
The problem is not that we use books, the problem is that the books (or whatever you want to call them) have evolved in the typically chaotic fashion of open source projects. And most of the content has been created by developers, who are notorious for creating documentation that simply iterates through features, functions, modules, GUI controls etc. That's fine for API documentation, but it just doesn't work for anything else.
One of the fundamental principles of technical communication is that good documentation is NEVER about the software, it's about the reader!
There are two basic questions we have to answer before we get anywhere: What are the job functions of the people who are reading this content? [This drives splitting up content into "Installation Guide", "Developer Guide", "Administration Guide" etc] and what is the reader trying to accomplish? [Which drives how you break things down into chapters like "Administering Users" and "Configuring Web Servers".] From the reader's perspective, our current structure makes absolutely no sense whatsoever. In fact, it's pretty much impenetrable. If I'm trying to work with images, for example, I get absolutely no value from having the image-related documentation scattered over five or six different locations (underneath oblique headings like "contributed modules" that don't even provide a clue about whether or not there might be image stuff to be found in that spot).
Until we start making the basic organizational units match the roles of the reader and the work that they're trying to do, it doesn't matter whether you use books, categories or anything else.
this probably sounds crazy,
this probably sounds crazy, but there are times when I've thought to myself "if we could only throw out the existing structure of documentation entirely and start over with a perfectly designed top-down view."
My thoughts are this: the documentation that exists was created over time through a process along the lines of making a bit of content that seems lacking on the site, then find the best place for that content to go and then stick it there. Ideally, the concept of "book," be it in Drupal parlance or an actual book meant for printing or download, you'd start the process by creating an outline. You would start with a top level view of what you were going to teach the reader, paint the broad strokes of the process, then go back and flesh out the details of each intermediate step along the way. In that way, you would have a really well thought-out book, with a cohesive message and a feeling that the information built on previous bits along the way towards the end. We don't have that, really.
Apart from starting from scratch like this, it is probably possible to do the outline process I mentioned here, then go back and add existing nodes to make them very roughly fit your outline, then edit the nodes and add new ones where necessary to make the whole thing gel properly.
I know this is probably more than anyone wants to think about us doing, but if we really want to make the documentation stellar, we might have to consider some difficult things along these lines. Please nobody shoot me! :P The conversation was about rethinking documentation so I figured I would throw that out there and see what everyone thought.
-=- christopher
-=- christopher
ruc
The existing documentation is only about 1400 pages. If someone creates a decent structure for us to fill in and let's us copy and paste from existing pages, each user could create 3-4 pages from existing content. That would mean we'd only need 200-250 people working on the documentation. :)
Dave
What I'm wondering is.. of
What I'm wondering is.. of the existing 1400 pages or so, how much overlap is there and how much of it could be distilled in a more clear, concise way? The card sort that has happened at the top level of the site's architecture really should happen with the documentation. It's the kind of thing that is pretty involved and time consuming, and might be more easily done in a room with real cards. We just completed a card sort with about 2500 terms and it took us about a week and a half's time, working a half day at a time. The online tool that Leisa has been using for drupal.org, I think, would be difficult with that many terms from a visualization perspective, but if you guys wanted to give it a shot, I could donate the cash to get us an account on there for that process (it's only free for a sort of 30 cards or less, I believe.)
I told ya it would probably sound crazy :P
-=- christopher
-=- christopher
Node relativity
For documentation I really like the Node relativity module. And with it we could restructure the existing documentation without removing the documentation itself. It would require hours of work to association the existing nodes but once done it would be a great view. The left menu would then only contain the top level section and once in the section the relative pages are listed at the bottom of the current page.
The idea for the tabs per Drupal version may be good using a taxonomy vocabulary term to tag the document and using the tag as the tab. However, this is the least of the problems and may cause more problems since some documentation is generic regardless of version.
"...find what you need..."
Even though the "Drupal Project - Knowledge GUI" is 7 months out-of-date now, I still find it easier to expand this entire outline in my browser to search for the drupal topic that I'm interested in and then follow the link to the specific d.o page. Once at the d.o page, it's relatively easy to see if the page is version-specific.
Couldn't we get drupal to generate a similar page of all these doc-specific links automatically from the handbook links of the left menu? This way, if users didn't prefer the current handbook layout, they would still have an easy method to quickly search all of docs for the info they desired. Maybe the page could automatically include tags for each link as well.
2 cents worth and not a penny more!
I think the learning curve, and therefore the quality and accessibility of the documentation is one of the areas, if not the factor holding Drupal back from wider adoption.
I don't have specific answers, but thinking while writing, to be really iconoclastic:
Note regarding eating our own dog food we can't say that we're even doing this when it comes to Search can we?
Of course the big advantage of dog food is supposed to be that it forces improvements in the platform, but how much love has Book (or core Search for that matter) gotten in the last few years? And was it ever intended to manage a multi-faceted community-driven search container for barely-structured moving-target information furballs? (Yes I'm writing this at 3am. . .)
Heresy I know, so the rest is this will (mostly) stay within the current state of affairs' major limitations.
So I obviously agree with questioning the use of Book at all. Even more, seems to me the fundamental idea of top-down structuring, each node only gets one parent in the hierarchy, only works in a much more controlled environment.
I think leveraging taxonomy's the way to go, but again to be effective for multiple vocabularies (NOT free tagging) it needs if not pro editors, then at least a small "authoritative" group of doc team members focused on just maintaining the integrity of the vocabularies and making sure new/edited content is accurately tagged, would IMO yield a tremendous return.
Initial browsing via dynamically generated but filterable listings, maybe pseudo-hierarchical Views w exposed filters? OK if some stuff shows up in multiple places. . .
After topic and version, the next key filter is skill/experience level - that gives us 3 vocabs - LEVEL - VERSION - TOPICS.
Let the poor noob start out by just browsing and searching through stuff written with him in mind, only expanding into the more techie stuff when he doesn't find what he's looking for in intro-level materials. But that's not the basis for putting up semantic firewalls like separate Books, just another aspect to filter on - it's a continuous scale from newbie to wizard, not separate audiences.
Just using Drupal effectively on your first basic corporate brochure site requires bootstrapping your level up that logarithmic learning curve ASAP!
The version applicability issue's critical to solve, again, not the basis for separate Books, or it takes longer for good newbie-useful docs to get written than even getting all the contrib modules caught up with each major release.
Sub-topic granularity is a major problem (AFAICT back to other-dog-food heresy) I can't see getting solved within Drupal, more like on-the-fly XML. Ideally "behind the scenes" you wouldn't have separate "big chunk" documents, but tagged sections (this bit applies to 4 & 5, this to all, this to 5 & 6, etc) that get assembled into pages on the fly. this just doesn't get done in Drupal as it stands now.
FWIW I like the UI of the API's version tabs.
If we can't fix this, then again, let me start browsing/searching a return set specific to my major version, but let me expand it if I need to, as now with Theming info, much of the D6 stuff is missing from the D5 sections but very much applicable.
Better search is critical - Faceted? Solr? Google-driven (what we're doing now anyway and for me it works OK but would be nice if that dog food got better)
My head hurts. . .
To repeat I think this is the area holding Drupal back from wider adoption.
There are some good
There are some good proposals here. Thanks.
Do folks like the idea of flat taxonomy driven listings instead of book hierarchy? I'm not so sure about that, becuase we can and do hav that already with the tags that are applied to book pages. Perhaps we jst need to emphasize more the tag based browsing (i.e. facets, etc.).
Would be helpful to omit the discussion about dogfood and tools in general. Just visualize a great solution. I am pretty confident that Drupal can meet it, but if it doesn;t then a different tool is quite acceptable. But really, tool talk comes later.
Let's try it the other way round
We have all written what we do not like in current documentation - let's now try what we'd like to see in new documentation and then we'll try to achieve it.
Here's my list:
An example how I would like it to be (for themes) for different detail levels:
If you have a look at current docs you'll see that tries to achieve this at least for theming guide, but docs we get are chaotic and so incomplete that you can barely see the structure. The other problem it has been attempted for theming only - the rest of the docs is in even worse state
Caveat: I do not have
Caveat: I do not have particularly clear or coherant thoughts here. My head is swimming a bit so I'm just spewing stuff out.;-)
Facted search and keyword tagging will do a lot for helping people find what they need. If we did just that with our existing set up we would probably relieve a lot of burden and annoyance. But, that said, we obviously need to also have a better base organization.
I agree that most people are looking for functional categories to work from and we should have a top-level org that helps people down the path of the task they are trying to accomplish.
From another perspective, when I think of the docs in broad strokes, in terms of types of content that can help me accomplish a task, this is roughly what I see:
Tutorials: step-by-step walkthroughs. You start at a defined place, go through the steps and end up at a defined place.
Examples: Cookbook, Build a module
Reference: Quick reference guides and conceptual docs
Examples: Terminology, API, core template suggestions, What are nodes really, the concept of FAPI, how the theme system works
Buckets o' Stuff: Helpful info all over the board
Examples: Snippets and "How I solved x"
I feel like tutorials and reference material should be internally organized in a more book-like way since those ar the things that I tend to go to and want to have presented to me in an ordered way. Buckets o' Stuff are not as well served in an organized "book." They make more sense as the bucket they are with lots of ways to slice and dice them. These would even probably be better served to be a different content type.
So, basically if I went into the Customizing > Theming section, I'd see tutorials I could follow if I wanted someoe to take me by the hand, a reference section and then a tagged, searchable "bucket of useful crap" with the most common terms highlighted, like "user profile", "menus", "3-column" or whatever. I could maybe pick a version at this top-level and say i only want to see the stuff for D6 and the page would narrow down. Or I could browse through and just click tabs on individual pages to see version-specific stuff. Now this is all assuming I wanted to start ina top-down way anyway. With our lovely tags and faceted search I could just search for my task and go about it that way too.
Instead of manually placing everything where it needs to be, these lists of tutorials/reference/bucket are created from tags and types. This way a snippet or tutorial could be in the theming section as well as the admin guide, if it applied to both.
Hm, so that is just my attempt to synthesize what others have said and how my mind tries to wrap around this. I think wireframing some of this stuff up would be immensely useful for both us and MBD to get a handle on what we each envision. I'll try to work on that this week for myself.
(Oh, and yes I agree that having the API integrated into the rest of it would be ideal. How that would or wouldn't work technically, I don't know, but it is an ideal to shoot for.)
As an aside, I think that processes like evaluation/moderation and roadmaps for needed docs is something to be looked at after we figure out what to do with what we already have. This is a volunteer group so planning all the work they need to do at this point is OT for me.
Lullabot loves you
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans
Learn Drupal online at Drupalize.me
General content recommendation
This week we added a general content recommendation engine to the ApacheSolr search engine. It's pretty cool. You can make an arbitrary number of blocks with different configurations and recommendation vectors, and when looking at a node, they recommend other nodes that are similar.
Internationalization
Just bringing back another must-have item: internationalization.
We - non-English-speaking communities - really need that.
What are the major issues in this case? People management, perhaps?
It's not "either-or"
Let's pretend for half a second that we're not limited to "Drupal's capabilities" and dog food and all that stuff. Let's pretend we want to create the world's most awesomest online tool for interacting with, and contributing to, Drupal documentation. A few suggestions above are focused on specific technologies (this way OR that way). I don't think it needs to be an "either-or" approach.
I'll define my bias first: I don't I personally like the current structure of sorting content by "type" (e.g. tutorial vs. video) BUT I like interacting with the API docs exactly the way they are. I do think the 'general'/user-contrib documentation it should be available per topic at the highest level of organization and then "types" of documents below those topics. I personally /like/ the API docs the way it is now and I use it a lot. If it were integrated into the main docs I'm worried I would lose it as a "quick reference."
I like the topics identified in:
http://groups.drupal.org/node/15965#comment-54403
But I'm not sure that we need to be thinking in terms of "books" or "guides" or (essentially) the print model for grouping relevant content. I've posted two screenshots in the redesign group that look at a different way of tackling the "entry" page for the documentation.
Both include the option to highlight "feature" articles; include "new/recent" pages and include a list of sub-topics that are available for that larger topic.
http://flickr.com/photos/emmajane/2987879578/
http://flickr.com/photos/emmajane/2987879572/
When I looked at these two sites a few more ideas came up:
- what if there was a "filter" at the top of the "topic" page allowed you to customize the launch page by (version of Drupal, type of content, etc). This would be much teh same as the filter on the download modules/theme sections of d.o.
- sorting content by popularity may help to highlight general usability issues (the same document being referenced over and over again).
- content can still be stored in "books" or whatever content type is best, but there is no reason that we need to be limited to a single approach on the entry pages (and there's also no reason why we wouldn't have multiple entry points according to search preferences, learning styles, and type/depth of information required).
More later as things continue to focus... :)
sounds great to me
I also like the way api.drupal.org works at the moment - I usually want to look up a specific function and it's references, sometimes compare it between versions of Drupal - and api.drupal.org lets me do exactly that. Some things like the hook and fapi references it'd be nice to refactor - but those are relatively minor changes to how the site works in general. It'd be good to have it appear more integrated into documentation though, even if it remains a separate site technically.
With the handbook, my entrance to any particular page is almost always via google, sometimes project pages, sometimes drupal.org search. So while I think the tree structure is good for something like 'getting started', having more of a dynamic homepage - and hopefully using tagging etc. for structure would help things a lot. I only normally use the tree structure if I either know exactly where something is, and clicking through is quicker than googling, or because I'm working on documentation. Pushing content stuff up to the top - even if it's not relevant to what someone's looking for at that moment, would convey how active the documentation team is, highlight high quality content that might be several levels deep in the book hierarchy etc., could help things a lot.
I wish I had this sooner,
I wish I had said this sooner, but this is EXACTLY how I feel on this issue.
I think if the various documentation pages were tagged and a form was presented that let me filter by topic, and by version of Drupal, it would be very handy.
The tree structure is only useful if you know where something is because of how fractured and disorganized it is. We could learn a lot from the structure these various Drupal guidebooks have in common for the structure our handbook should have.
Dave
another popularity-based approach
Here's another site that uses popularity and categories for snippets of code.
http://snipplr.com/
There's nothing outrageously new about it, but for some reason I felt like I'd be able to find the important stuff again... mostly because there was an option to "favorite" any of the snippets once I'd logged in.
Some useful questions (in order of importance)
A few more thoughts on the redesign and documentation
A few more thoughts on how to improve the existing documentation.
1. Integrate documentation with project pages
Are there any plans to get documentation onto project pages or are those pages off-limits? I have always thought module-specific handbook pages should be shifted to a subsection of the Project pages with hands-on articles given prominent links/placement on the project home. It makes little sense to have articles like tutorials, comparisons etc separate from where peeps grab the module from since the first thing users want to do after downloading a module is do something with it.
Too radical? Then how about documentation having a dedicated section (not just a single link) of real estate on the project pages with a link to that module's main page in the handbook as well as links to key tutorials or other relevant articles. The current 'Read more documentation' link is a mixed bag. Often it goes to the developer's blog or to a page no longer relevant. This might also spur on developers to write a little documentation, too.
2. Integrate documentation with the API
I agree with emmajane that the API should remain a sanctuary, however, putting API tips closer to where the code lives would be beneficial. Of course any contributed content here would need to be short on words so as not to detract from the API's handy quick reference aspect. So rather than clutter the API, extend it with existing, concise examples. If those examples aren't in the API itself, then at least some ingoing/outgoing links between the API and the handbook.
3. Tabs are good
As others have pointed out, the tabbed pages are really effective for comparing versions. I would love to see this applied to a general handbook about Drupal core and documentation in general. As per the API, it doesn't matter if there is no content for a specific version (it might encourage others to write it) or if content is the same across versions. Separating content by version also makes it more user-friendly, less ambiguous and easier to write and check.
4. Have a single handbook about Drupal core
After shifting out contributed module stuff, roll Getting Started, Drupal Cookbook, Beyond the Basics etc into one main book addressing the key aspects of Drupal: installation, menus, core modules, etc. Theming is an obvious another chapter. Each of the chapters would be substantial but at least everything addressing the same topic would be together. As mentioned above using tabbed pages would enable content to stay together regardless of version. Furthermore, handbook chapters etc should be discrete and unify all existing content on that topic. If there is a chapter called Installing Drupal, then that should become the go-to place for installation and include all of the 30+ pages, videos, tutorials on installing Drupal (for D6, D5, D4, WAMP, MAMP, Ubuntu etc) scattered throughout the handbooks.
Anyway, those are just some initial ideas. Feedback welcome.
project docs
Just a quick reply to 1. Integrate documentation with project pages.
This is being discussed in a few threads re: the project pages at:
http://groups.drupal.org/node/15295
http://groups.drupal.org/node/15199
Lullabot loves you
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans
Learn Drupal online at Drupalize.me
Structure of module documentation?
Thanks for the heads up. Sounds like others are on the same wavelength and module documentation IS going to be
moved out of the handbooks to the project pages. add1sun, is this confirmed or are the redesign team
and project folks waiting on the documentation team to provide more details about what format the
module docs will take in their new home? Is there another thread where this is already being discussed?
No need to "move" stuff!
It's fine to move the documentation to the project pages but I don't understand why we would want it to disappear from the handbooks!
The same content can appear in multiple contexts. I agree that we should have the documentation for a specific module displayed within the context of the project, but that content can still be used in the handbook.
However when it appears in the handbook it should be used in a very different context and only if it serves a specific objective. In other words, definitely NOT as a random mishmash of every darn module in no particular order (the status quo), but repurposed to guide users through complex sets of tasks. For example, we could have sections on working with images and working with geographic information that incorporate both conceptual overviews written for the topic and project documentation that's appropriate for the context.
move, join, remove
As always, I think it will be the content of the documentation that will determine the best treatment for each "page." I hope that we are able to to a combination of things with the module-related pages...
Sometimes it will be best to move the documentation completely. For example: install and configuration instructions for individual modules don't really need to be in the "handbook." Of course there should be links back to the project pages for the install instructions. Right now, however, we have the README files for many project pages smooshed into the handbook pages because that was the only way to get them into the d.o Web site for people to see. Without additional context or content these pages really do belong to the project. Moving them out, and including better links to the project pages, makes the best sense.
Sometimes joining instructions to both the projects and the handbook will be the best idea. Maybe this is done through tagging (this page applies to Project XYZ and therefore is linked from that page), or related nodes or something like that. These pages, in my mind, would contain "meta" information. Not specific set up instructions, but broader "how to use this module with another module" or "how to reallllly take advantage of this module to make your site zing in this complicated setup." Basically things that use the module in the broader sense of building a Web site, but aren't confined to just install/configure information, should be joined.
And finally there is remove. As we start filtering through the pages we may find there is some information that is simply no longer relevant. For example a really old set of install instructions from the 4.x days. I know we don't really "delete" things, but there are module-related pages that will surface as being neither a candidate for moving, or joining because they are simply no longer valid.
Moving stuff out would help declutter the handbook
It's fine to move the documentation to the project pages but I don't understand why we would want it to disappear
from the handbooks!
If the project pages become THE reference point for a particular module, then I feel there is no need for a handbook
section to exist since all relevant pages would be contained within the subsection of the project page. Developing
a strong, consistent documentation section on the project page would establish it as THE place to find in-depth
information about a module. In time, users would come to understand that if they want to find out about
CCK, they go straight to the project page or CCK/documentation. It might also encourage users to contribute
a quick tip because they could easily see what's missing.
Where there is a clear opportunity to remove stuff from the handbooks, I think it should be taken. Otherwise the
1400+ pages will continue to grow in a haphazard fashion due to the confusion of where something belongs.
The Contributed Modules section is the easiest to break up since it's divided by project. And adhoc pages
within existing handbooks that are relevant to a specific module are easy to spot. The content itself is also easier to
unify, compared to say something like the current plans to rejig the Theme Guide.
The same content can appear in multiple contexts. I agree that we should have the documentation for a specific module displayed within the context of the project, but that content can still be used in the handbook.
Yes, multiple entry visas are good! :) But I would rather see handbook pages refashioned to include a Related
Links section rather than putting the same content in multiple sections or content on the same thing in different places.
Otherwise the user will always wonder if they are getting the complete picture after visiting the project page.
Personally, I would like to see non-core documentation break out of the handbook with the good stuff reworked into
structured content, whether it be a step-by-step guide on how to create a custom content type with CCK or 150
words on how to use theme_imagecache(). In most cases, the objective is the same: show people how to do/use
something. Tutorial, How-To, Recipe, Step-by-Step -- these are all just handles for the same thing.
For example, we could have sections on working with images and working with geographic information that
incorporate both conceptual overviews written for the topic and project documentation that's appropriate for
the context.
Yes! I agree there should be these types of articles on Drupal, but at the same time, I wish Drupal didn't
try to shoehorn everything into the handbook. Instead of HansBKK's "Comparison of Image Modules" ending
up in the handbook, it could be edited into a multi-part feature article, plugged on the front page of
Drupal for a few weeks and become the first of an ongoing series of more conceptual or broader articles. The final
article could then be linked off the ImageField, Image etc project pages.
Basically, I think the redesign presents an opportunity for Drupal to not just shuffle pages in the handbook, but also
to really rethink documentation in terms of what it is and how and where it's presented.
I don't like separating core and project
If the project pages become THE reference point for a particular module, then I feel there is no need for a handbook
section to exist since all relevant pages would be contained within the subsection of the project page.
I disagree. This idea of separate "project" and "core "is only meaningful within the Drupal community (and even then, not to everyone). It doesn't make any sense to an outsider and I believe that it's really irrelevant to how documentation is structured. Documentation should be organized around the roles that people play and the tasks that they have to do, not around the internal structure of the organization that developed the software.
If someone is in charge of managing users, all the important information about managing users should be brought together and arranged in a meaningful way. We shouldn't tell people "yeah some user management stuff is here cause it's what we call 'core' but other user management stuff is in basically random order over there cause that's what we call 'project'".
I agree that the handbooks are cluttered but the root cause is that the structure is completely irrational. If the content was structured according to industry norms they would be much slimmer and easier to grok.
storing vs. viewing
I think it's important to throw out a wee tiny comment here to remind ourselves that "storing" the information in a specific place doesn't mean it will only be "viewed" in that location.
I might be getting confused, but I want to make sure that we end up with a documentation section that only talks about core and you have to go elsewhere for contributed information. I do, however, think that module-specific information is best placed with the rest of the module in some cases.
In the book sense of the word I have been thinking of the project pages as being the "appendix of information for this module that you need to know to make the module work" whereas the handbook has the good stuff. :) Sorting out all the module-specific documentation allows more interesting documentation to surface in the "handbook" section (e.g. how to combine modules to create a wiki or an image gallery). With a LOT of links back to the "appendix" if people don't have the skills they need to follow the instructions in the handbook. For example: I want to use TinyMCE. There are a lot of steps to installing this module...where do I go? To install and configure I go to the Project Page for the module.
In my mind "anything" could be featured! All content needs to be carefully placed (and appropriately tagged) so that we don't end up with a new content type for "Featured" (the way we currently have Videos vs. Tutorials vs. etc).
Lee, the idea to separate
Lee, the idea to separate out module documentation is not driven by a core vs project mentality, but by the same task-based approach you speak of! :) Installing and configuring a module is the tip of the iceberg. Each module, however, has key tasks required to use it which vary in terms of proficiency with Drupal and to some extent role. It's these kinds of tasks which I would like to see documented and plugged on the project page in some form (e.g. as a teaser with title, thumbnail and summary) rather than buried in the handbook.
The idea to keep stuff together in one place stems from the fact that the current handbook is unusable as a book -- you can find
anything via Google, of course -- because same topic information is all over the shop.
I'd actually like to hear more of your ideas about a task-based approach to documentation as I agree this is the way forward. I mentioned in my first post how I thought the Installing Drupal section could be improved by rolling all pages related to installing Drupal into one section. You also raised this in one of your posts so perhaps we are on the same page. Are there concrete plans to make this a reality?
Re: a role-based approach to documentation, I am not so keen on that since Drupal users wear many hats.
emmajane, you're right in saying where the information is stored is not the dealbreaker here, but I do think documentation needs to be more upfront on Drupal, and that Drupal should aim to have a consistent model for how documentation is presented and written. If the home of module documentation is going to be as a subsection of the handbook, then let's work on establishing/promoting that project-to-handbook association so we can bridge the disconnect between the two.
Why roles matter
I realize that people often wear many hats in the course of a day, but they are only wearing one hat in the moment when they come to the documentation looking for an answer to a specific question. When you organize the doc set by roles, it's much much clearer where the reader has to go to find the answer.
In fact, we do this already because the developer stuff is all in the developer guide and the themer stuff is in the theming guide. I think that this is a good thing but there are at least two other roles which need to be recognized: the person who does the day to day admin stuff like adding and removing users, maintenance, logs etc and the people who build, design, customize sites. .
In the Drupal 6 guide, we have site building as a subset of administration and that just doesn't make sense to me. These are actually two separate and distinct domains of knowledge. One is not a subset of the other.
Administration is only how you keep the site up and running. There should be a separate guide for the business architects, planners, developers, creative people etc. to figure how the site is going to be put together.
Are roles too black and white?
Some tasks have a one-to-one relationship with certain roles, but not all. The only difference between how, say, a content manager and a developer achieve their goal is via the tools they use, which in turn are related to the complexity of the task. Kind of what HansBKK has said.
A content manager (who also doubles as an administrator) of a mum-and-dad website will use the Taxonomy and Menu UI to make their navigation system while a developer will delve into the API, write a custom module etc. What happens when the CM wants to make their primary links with a pink background and a blue border? Or do something not available out of the box with their menus? They will have to cross the line into another role. I think a section, for example, like Menus/Navigation which unites all content on that topic but breaks it up into tasks ranging from the no-brainer (using the Menu UI) to going the whole hog and creating a dynamic menu system with the API, is better as it doesn't box users into roles. I think users identify more with a task ("I want to create a menu.") than with a role per se but that's just my opinion.
In the end though it all comes back to structure. Perhaps a tagging sprint, of sorts, where members of the doc team could add tags to all 1400+pages would be beneficial in nutting out an overall structure. Even if just in a Google spreadsheet with the titles of pages in the first column and suggested coloured tags in the others. We could start with some base categories but also
allow members to add new terms. Then we could tally up terms to identify possible new candidates for sections, merge others.
A clearer picture as to the best way to reorganise the handbooks might then emerge.
Let me put it this way
Everything to do with building a site (outside of actually writing code) belongs together.
This includes:
Everything to do with the day to day operation of a site belongs together. This includes:
Whether or not you call them "roles", these are actually quite separate and distinct domains of knowledge. You could call them "how to build a site" and "how to keep your site up and running". And it doesn't matter if people sometimes work in one area and sometimes in the other. The important thing is that on seeing this documentation structure the reader will immediately (or very quickly) understand where to find the information that they're looking for. Am I building and configuring a site? Yes? Then I look under the "building a site" section/guide/heading. Am I managing a site that's already been set up? Yes? Then I look in the admin guide.
finer granularity possible
With a little more sorting, I think that you're absolutely on the right track. I agree that "beginner" and "advanced" aren't measurable and don't really mean anything. In the knitting world people only think that purling is hard because that's what they were told. It has nothing to do with the actual mechanics of the stitch, just the perception of difficulty passed down by others.
Back to Drupal...I would actually break content-related tasks into their own category...the "role" in this case would be a content manager. Or in the case of many of my clients, "site management" is actually, "content management." For these clients it would make sense to have a set of instructions that are all related to content tasks/management/etc. Managing users, for example, would be completely irrelevant, and managing cron jobs would never make sense.
Content-related tasks
- Configuring content types
- managing content
- managing categories
Well now you may be onto something.
It definitely makes more sense when you spell it out in terms of concrete, related tasks. I see light at the end of the tunnel! The examples you give are geared towards administrators or content managers. A non-coder reference. Do you envision bundling all tasks involving coding into the Developer's Handbook? Where would you see my example of a tutorial on making dynamic menu system fitting in? Within a Menus section of the Developer's Handbook? Or somewhere else?
Re dynamic menu system
It's a good question and I'm not sure that there's one right answer. Although I can see a good argument for keeping everything on the subject of menus (for example) together, I would lean toward keeping all the code stuff in a separate developer guide but making sure that there are good cross references in the regular documentation. Something like "here's how you build menus using the out-of-the-box tools. You can also use the Drupal API to provide custom menu functionality. For more information, see blah blah in the developer guide".
People who write code are a subset of the broader user community and their information needs are not the same as that of a person who just wants to add and remove a menu item through the UI.
I know I've just been arguing to keep related stuff together but I think my argument breaks down when it comes to working with code.
developers use the UI too
While the development documentation is about how to develop using Drupal's APIs, if a developer is building a whole site themselves (as opposed to working in a large team), they'll be using the menu and taxonomy modules (and the views and CCK UIs) most likely the same as anyone else.
I started using Drupal when I had pretty much zero coding skills whatsoever, and one thing I've noticed is the high number of people who've clearly been developing for a while showing up in #drupal completely confused trying to build a custom module for something they could've done using CCK, Views or another major contrib module in a couple of minutes. Things like building custom forms, creating node types etc. etc. - a lot of code gets written unnecessarily, and often really badly - and at least in part, this is likely because we don't have easy to find information about building forms (do I use FAPI or CCK for that? How would I decide?) - etc. etc.
So while I agree about having task based documentation, I hope we can move a little bit away from 'the coder', 'the themer', 'the site builder', and focus on 'what do you want to do' rather than 'how do you want to do it' that would help a lot. Many new users to Drupal get fixated on the 'how' because they can't easily find answers to the 'what'.
+1
A couple of specific responses...
1. Integrate documentation with project pages
/me facepalms! How obvious to have a closer tie between modules/projects and their documentation. My only heads up is that we shouldn't expect the developers to write the documentation just because it's closer. Remember that a developer is (almost always) too close to a project to write truly exceptional documentation. That's the job of a documentation author to step away from a project and describe how it really works. :)
I do think it would be lovely if there was some (automated) way to pull out the README file from a project. In theory there could be a link to the CVS with the latest version of the text? e.g. http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/ahah_forms/... Integrating documentation with projects will only continue to grow especially with the Advanced Help module http://drupal.org/project/advanced_help. Whatever we can do to help improve communication/sharing/etc would be great!
2. Integrate documentation with API
I also really like the idea of having the API documentation integrated as well as having it available separately. Maybe another category that allows free tagging to give specific functions that are relevant to the page displayed as a footer or a sidebar or something? I'm thinking of the PHP documentation that has "see also" at the bottom of each function definition. For example: http://ca.php.net/manual/en/function.array-push.php has "see also" array_pop(), array_shift(), array_unshift(). I know it's not quite the same, but it's a start...
3 key "dimensions"
TOPICS - LEVEL - VERSION
I earlier called these "vocabularies" but the first one - LEVEL (the user's level of skills and experience) - should IMO drive the "book like" organization. The lower the reader is in the learning curve, the more s/he needs a good hand-holding, step-by-step structure, as they don't even know the jargon well enough to search for it yet! Those who have already passed a certain point in the Drupal learning curve have also probably figured out how to find the needles in the haystack. But the current division of Beyond the Basics is of course way too rough, there's a lot more to "basics" than core, and in fact skill level is a continuous gradation, not clear divisions - so don't make level part of the navigation hierarchy at all.
So IMO the navigation hierarchy - should be by tasks/topic area, with "main pages" of very structured step-by-step introductory information for beginners, and lots of jargon clarification and cross-references to related topics in different parts of the tree.
Then under a given topic "main page", a whole collection of nodes tagged with that topic can be presented, and should be sortable/filterable by "intended audience/skill LEVEL", Drupal version it applies to, date last updated, and maybe the different "information types" - recipe vs howto vs snippet (but IMO these are often arbitrary distinctions - maybe OK as tags but definitely not part of the navigation hierarchy).
So keep navigation hierarchy to one "dimension" - task/TOPIC, but focussed on the needs of the newbie. The other "dimensions" are just ways to group the pages pertaining to that topic - search results? filtered Views?
Let the more advanced users find what they're looking for via a really excellent search facility if/when that's possible (and in the meantime we'll keep using our Firefox custom search engines :)
The toughest dimension to wrangle is Version - IMO at this point in time the "backbone" main pages of the hierarchical pages should contain information relevant to both D5 and D6, all version-specific information should be in cross-ref'd sub-pages.
At some point in the future (after D7 +key contrib modules ship stable (vote by the doc team community?) + 3 months?) then we start working our way down the hierarchy, moving the information that's true for both D6 + D7 in to the hierarchical "spine pages", deleting/adding/editing the version-specific subpages as we go.
I feel very strongly that version-applicability should be at the very bottom of any navigation hierarchy, as this differentiation seems to be the hardest to maintain. I'm currently just as likely to find information of value to D5 in old D4 or newer D6 pages, please don't allow them to be hidden off in other parts of the tree as has started to happen, makes the whole doc set a lot less usable.
Sorry this isn't more coherent, just a braindump. . .
Skill level is tricky
Organizing material by skill level is very tricky. Perhaps it could be one of the alternative ways of presenting information, but it definitely is not what you want as a primary structure. I have to say that it actually drives me crazy that this is the route that Drupal has gone (i.e. Getting Started and Beyond the Basics)
The problem is that there will never ever be a clear idea of who is a beginner and who is an expert. Some people know a lot about some things and nothing about other things. Some people think they are experts but they actually don't know some important basics.
Worse than that, people who are just starting out with Drupal will often need information on something that's very complex (maybe without realizing that what they want to do is actually quite difficult). They'll go all through the "beginner" section and not understand why the information they're looking for is not there.
Even after two years working with Drupal (and many years working as a technical editor), I still have no idea whether any particular question would be answered in the Getting Started or the Beyond the Basics sections. If I wanted to contribute a new page, I wouldn't know where to put it.
A good search function would be helpful but whether you're expert or beginner you still need each page placed in a coherent structure so that when you click on a search result you get the major bonus of a well-designed context. In other words, that you can see at a glance that there is related information and that the related information is arranged in a very meaningful way (e.g. stuff to do before this procedure, stuff to do later, higher level information, lower level information).
Don't mean organize hierarchy by skill level
Just that "main spine" pages target audience should IMO be somewhat low on the learning curve - use sub-pages for hardcore tech - or on the other hand pages written specifically for rank noobs.
Setting a consistent tone for the "main thread" is helpful rather than jumping all over the map from one branch to the next as now.
I think it might be constructive to have a structured discussion on this topic as a separate thread here?
(cross-posting)
My thinking is that the main pages should cover what's in common between D5 and D6, sub-pages for stuff that applies only to one or the other (or D4 or D7).
Sub-pages as parents for snippets on a certain topic, or recipes/howtos.
But all of these hanging off the main page on a given topic, none of these other factors (version level type) to be "firewalled" off in other locations.
Obviously cross referencing between sections where needed.
some thoughts on a strategy...
I've just posted some thoughts on our strategy for the documentation section here:
http://www.disambiguity.com/drupalorg-redesign-a-strategy-for-the-docume...
I'd love to get your thoughts on it if possible. (I would usually cross-post but based on past experience i think it may be a formatting nightmare - happy for you to comment here rather than there tho' if you prefer!) We're also working up this approach for inclusion in the next iteration to be released later this week so you'll have a chance to play with what we've done then also.
thanks in advance,
Leisa
leisa reichelt - disambiguity.com
@leisa
suggestions
Looks like great ideas Leisa, and I have posted there, but just to follow up on your posting's format:
I realize you're working in agile quick-and-dirty mode, here, but take a little more trouble to get clearer diagrams posted and re-working the IM? back-and-forth into something more accessible would really help communicate your ideas better.
Or do you only want highly motivated people to participate? :)
a little unusual...
lol. I know, the format was a little unorthodox this week.
I do usually try to write up a proper post to outline the strategy but we were very pushed for time this week and the ideas were quite embryonic, so I thought that this might be better than nothing! I know some people got some value from it but I appreciate it was a little harder work than usual.
As ever, the weekly prototype is the best place to keep track of what we're doing!
thanks for taking the trouble - I do appreciate it!
leisa reichelt - disambiguity.com
@leisa
Getting Started Must Die!
Can we please, please, please do something with the Getting Started landing page? Like maybe take it out behind the shed and end its wretched, misbegotten existence once and for all?
Right off the bat, "Getting Started" is a really mediocre title for documentation. Aside from the vaguely patronizing tone (who are you to tell me where to start?), it speaks to noone and it certainly has no clear scope. You only have to look at the thirteen (count-em!) major topics now infesting the GS landing page to realize that literally anything in the Drupal universe could conceivably fall under the rubric of "getting started".
The really funny thing is that nowhere on the "Getting Started" page does it mention how one might go about getting the software installed. I don't know about you folks, but when I think of "getting started" with software that's actually the only thing that comes immediately to mind and, in fact, I'd kinda like to see an "installation guide" right on the MAIN documentation landing page (let alone the GS page)
The GS landing page is a really a classic example of how far out of whack you can get with documentation when you don't have a relentless focus on the user and what it is the user wants to do. Rather than help him get going, we push a whole bunch of pointless (pointless at this moment) stuff like a list of core modules and the 200 Drupal FAQs.
We have to kill this Getting Started nonsense. We really do.
' it speaks to noone and it certainly has no clear scope.'
I think this is where you nail the problem: Getting Started '...speaks to noone and it certainly has no clear scope.'
In the now quite numerous interviews I have conducted and observed 'Getting Started' is a term that new player are looking for. We either need to keep it or come up with a similarly attractive path for them to follow.
but the biggest issue is this: who is Drupal for? Who are we talking to and what are we telling them?
the lack of clarity around these questions I think is key to the fluffiness both of the getting started page and some other copy around the current iteration (and previous of course).
For example - for many of the people I've spoken to, getting them to 'download' Drupal would be the worst possible start. We wouldn't see them for dust. There are different 'good' starting points for different people...
So, I definitely agree that the current Getting Started page is broken. I'm not sure (although I may) agree that Getting Started could die.
I'd welcome any thoughts you (and others) have on the topic.
leisa reichelt - disambiguity.com
user experience consultant (design research and user centred design)
working with Mark Boulton Design on the drupal.org redesign project
leisa reichelt - disambiguity.com
@leisa
I agree with Leisa's
I agree with Leisa's comments. If "Getting Started" is the first thing that people new to Drupal will be reading, than it needs to do a better job of communicating what the software is, what it can do well, and what it does not do well. As currently written, the "Getting Started" section is targeted at helping people understand the technical nuts-and-bolts of Drupal, not giving them information that might help them evaluate whether or not it's a good choice to solve their particular problem, or help them out if they've "inherited" a Drupal site that they know nothing about.
The "Getting Started" section should be a warm and friendly introduction/orientation that clearly explains in non-technical language the points of difference between the approach taken by Drupal and that taken by other software in the marketplace (Wordpress, Joomla, etc.). It might also be a good place to talk about the different kinds of things that have been done with Drupal, and feature testimonials by people talking about how it helped them solve their problem. It should also (as the current design iterations do) point people toward finding out more, whether it's through the forums, the IRC community, or from a commercial concern.
There's definitely a place for the technical orientation as well, and I think having it is vital, but there needs to be a little more foundation for the non-technical user laid down first and some firm establishment of expectations. If your primary Web CMS experience is with WordPress, and you try to jump into Drupal without any idea what it's about, you're probably going to end up being in over your head very quickly. Conversely, if your primary experience is with a commercial product like Day or Vignette, and you're trying to evaluate whether Drupal might have a place in your technology stack, the current "Getting Started" section is going to leave you very underwhelmed. These are the folks that we need to be talking to, and once we've reeled them in, then we can recruit them as active project developers.
also in the docs team issue queue
I started a GS-related thread there, and have posted this issue there also for feedback.
http://drupal.org/node/337079
Your comments about clarity of target audience are spot-on. From a marketing POV we'd love Drupal to be for everyone but it's not. And 99% of the incredibly brilliant work that keeps pushing the drop along at breakneck speed goes into developer-level enhancements, not usability. IMO, and from the POV of current reality (not good intentions) Drupal is a tool written by developers to solve their own problems.
Someone who's done just a little static HTML/CSS and otherwise are just app users, will find it a steep learning curve indeed, I'd say the equivalent of 20 hours a week for six months to get to any level of confidence. And IMO it's not any easier to set up a traditional "corporate brochure" site than something more complex, say a multi-user blog.
If someone isn't willing to put in this level of effort, I would honestly advise them to look elsewhere - right in the intro docs ("Don't Get Started" ? :) Marketeers don't like to do that, but believe me the noob starts scratching the surface, trying to find relevant docs, asking to-them-simple questions, the ones who don't love learning new stuff run away quick-smart anyway.
But OTOH someone who is looking for a learning environment, a platform to help them get from html/css to php/mysql and beyond, Drupal offers a lot - excellent coding standards, huge feature set, incredibly large, active and helpful community, huge haystack piles of useful documentation to search through :).
But it doesn't hold your hand, you've got to be a motivated bootstrapper with good research skills and a lot of time. If the docs can be made more useful - accessible and organized, and/or (maybe eventually) building a site made easier for non-wizards, then, then, then (I'm tired) that would be a good thing.
Dynamic doc features: Ajax, Javascript etc.
I'm wondering if there might be value in adding some dynamic features to the way we present documentation?
For example, I'm thinking it would be really sweet if the handbook TOCs that appear in the sidebar would just open themselves up dynamically on a mouseover so that you could access all the sub headings without necessarily leaving the page you're on.
Another thing that would be too cool for school would be to sprinkle some Ajax fairy dust on doc parents so that mousing over each child link would display the teaser of the child.
On versioning the Handbook's instructions and code snippets.
I've added an issue on preventing documentation forking to the Docs Queue that pertains directly to the discussion above. Please comment on it at http://drupal.org/node/339456.
This should allow us to maintain all the information pertaining to that topic inside a single handbook node, yet allow version-specific information to be highlighted. It even allows users to cycle through multiple versions of a set of instructions in order to see what's been changed from the last version of Drupal to the current version of Drupal.
______________________________
Senpai ~ Want a better WorkHabit? ~
Joel Farris | my 'certified to rock' score
Transparatech
http://transparatech.com
619.717.2805
Getting Started can work
Re: the GS debate, I think Getting Started as a handle is not the problem here. The issue is that the existing content in
the section has little to do with the title. I think there should still be a GS landing page, but it should be just that - a page (not a book) of
ten or so task-driven headings linking to child pages in an overall book which walk new users through basic site configuration (site info, permissions, roles), customisation (enabling/installing a theme) and site building (enabling blocks, basic menu creation) tasks - the out of the box stuff we do right after downloading Drupal when we are donning our administrator hat. Layout-wise, perhaps something like the main body of Firefox's GS page. This assumes that Getting Started kicks in AFTER a user has installed Drupal. That works for me, but do others feel the same?
Also +1 to having a dedicated Installing/Upgrading section on the main docs page.
We need a "What Links Here" link
The more restructuring I do, the more I dearly wish that each doc page had its own "What Links Here" link like they have in Wikipedia. This would allow me to easily find and fix any conflicts that might arise when changing the page title or moving chunks of content to other pages.
It would also be another way for the user to explore related content.
Book module doesn't work for large books
The book module - at least with its default interface - is nearly impossible to use when restructuring large books. If I'm trying to find the new parent, I have to scroll past many, many hundreds of links to get there. It's very tiring, confusing and a major disincentive to good housekeeping.
It would be great if it was possible to drag the child to a collapsed list that only shows the top level headings and then have whatever heading I dragged the child to, just spring open so I could drill down to the right parent.
Yeah, large books are a pain
This is moderately improved in Drupal 6 since you can at least select the book first and then the items to scroll through are limited to that book. That is my #1 reason I want d.o to move to 6. Refining the UI further for book module is definitely a recognized need and has been talked about, but at this point I don't know of anyone actively working on it. :-/ Definitely something to add to the "needs" list.
Lullabot loves you
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans
Learn Drupal online at Drupalize.me
my 2 cents
The documentation, and its relevancy is as essential to the Drupal community as is the development of the core code.
I have skimmed through the comments above and have a few suggestions.
sure it is a lot of work to reorganize the documentation, but think of all the hours we lose trying to find documentation. Lets begin a documentation project, that would leave the current documentation relatively untouched and begin building a parallel version better organized to where Drupal is evolving. Essentials would be cut and pasted from the existing documentation but not 100%. It would start off small, but could grow in time to replace the old system with something much more useful and usable.
I agree that Drupal should not necessarily be the tool for creating this. Maybe Wikimedia would be better, or somebody may have a better idea.
With a community working on 3-4 different versions of Drupal at the same time, and with documentation more complete for some versions than others, we need to come up with a better way to integrate the documentation. Rather than segregate it between versions, merge all documentation with annotations of how each feature/technique/module/etc varies between versions of Drupal.
The documentation should live in one place in the simplest hierarchy possible for reference material and a well-organized section for tutorial content. Projects and other informational pages can link directly to these.