Over the past several years there have been some lengthy discussions about the major problems with the doc information architecture, most particularly with the Getting Started and Beyond the Basics handbooks, both of which seem to do more to scramble and obscure content than to make it usable.

I'm ready to go ahead and do a very substantial fix on these two books and also to completely redo the doc landing page. I've done a mockup here: http://drupal.org/node/616986 which I'm hoping people will take a look at and give feedback.

I know there's a parallel effort to implement DITA principles (which I fully support) but I don't think this reorg will conflict and may make the DITA work much easier.

I'm thinking to set aside a few weekends (and maybe a few evenings) in mid-November to do this. So if anyone has a reason why I shouldn't just go ahead and do this, please speak up now.

Comments

bekasu’s picture

bekasu commented

Lee,
Could you add an entry in the references section for another page which we could list places to get contributed modules:
http://drupal.org/node/340271, www.drupalmodules.org

Perhaps under the writing your own code section, you could add a link to the 'pay for help' section-- i can't remember the site node and bless me if i can find it right now.

I think your approach certainly provides a clean, lite appearance.

Would be happy to help if you need it.

bekasu

add1sun’s picture

add1sun commented

Awesome! This looks like a good start and I have no objections to rearranging things now, since it will be a while before the new site/IA sees the light of day.

Before we actually move forward with this I'd like to get a better sense of what is going where by creating a mapping between old and new, even if it is pretty rough. I'm not entirely sure what is going in sections like the Site building guide, for example. Are we planning to create new top-level books (e.g. Creating a site) and then move other stuff underneath or are these just unlinked headings for the landing page? Do you have a place/change for the About Drupal and Getting Involved books?

leehunter’s picture

leehunter commented

Ok I've done a rough (very rough) and incomplete ToC for these proposed new books here: https://spreadsheets.google.com/ccc?key=0AoF6kBvoy1dUdEU2MGdfampjV28wV3Z...

The first sheet gives a general idea of how things would be moved around and the other sheets show the actual new ToCs.

I think the most radical change is that the contrib and core module stuff would no longer be in these big random heaps separate from everything but would be moved to wherever the best context is. For example, there's a whole bunch of documentation on certain contrib modules which are of specific interest to developers. These should really go to the Developer's Guide to improve the chance that a developer might stumble across them.

Re. the About Drupal and Getting Involved books, since these aren't documentation per se. (they're more like marketing information and internal procedural stuff) they should probably be kept separate from the documentation but with cross references available from the docs landing page.

I'm thinking that these would all be top level books -

  • Understanding Drupal
  • Installation Guide
  • Administration Guide
  • Structure Guide
  • Site Building Guide
  • Theming Guide
  • Developing for Drupal
  • References
  • Tutorials and Site Recipes

I'm not totally sure that the structure and site building guides need to be separate books but I like the idea of creating a distinction between developing the IA and implementing the business logic.

And I have to stress that there's no divine revelation here, just something that seems to work inside my own head and according to my past experience doing this kind of stuff. So I'm hoping people will jump in and give me guidance and feedback if it looks like I'm going off the rails here.

askandlearn’s picture

askandlearn commented

I like your categories but would maybe suggest something like this...thinking in terms of someone new to installing and using Drupal.

  • Understanding Drupal
  • Installation
  • Site Building and Administration
    • Administration
    • Users
    • Security
    • Theming
  • Developing for Drupal
  • References, Tutorials and Site Recipes

The research I've seen indicates that people can only keep 5-7 choices in their head at one time, especially if they are stressed or in a hurry - as people often are when trying new software. I am assuming the handbooks are mostly for newer folks since experienced people will look for help in forums and issue queues.

[edited for clarity]

leehunter’s picture

leehunter commented

In general, I agree that it's good to have as few books as possible but as Drupal has become increasingly complex (and mature) the documentation set has become very broad and very complex and it really needs to be partitioned by role. Otherwise, what you gain by having fewer books, you lose when they open the book and find that there are an overwhelming number of sections, most of which are not relevant to the question they have in mind.

For example, administration (day to day activities), site building and theming are three distinct domains. Although many people do a bit of each, the roles and responsibilities are different and there is not a great deal of overlap in terms of content. If you have a separate theming guide, the people who specialize in theming can really "own" that book and focus on that content. The theming guide is already a very substantial document on its own so I'm not sure that placing it inside another really massive document would be useful. There's also enough just on administration to fill a typical software guide. And then we get to all the structural and site building stuff where there's already a vast amount of information, easily enough to fill several thick volumes.

I do appreciate your point about people only having capacity for x number of choices but I think I've addressed this issue by grouping the books on the proposed landing page http://drupal.org/node/616986. That way, people can scan through a smaller group of categories (5) but still be able to click directly to the most relevant content.

askandlearn’s picture

askandlearn commented

Good points. Actually, the categories you have at http://drupal.org/node/616986 do address the issue of manageable categories quite well. My comment was a response to your list in post #3 above. I should have taken a look at the link first. My bad.

I'm coming at this as a non-programming site builder and administrator who is a big fan of Drupal. I would like to help people get Drupal installed and tweaked as easily as possible so I'm all about relentless simplification and clarification. I'll just be bold about that and someone can tell me if I step on toes. I surely don't mean to.

As a simple example of little details that mean a lot, eliminating extra words makes this easier (faster) to scan and understand.

Original list (21 words)
* Understanding Drupal
* Installation Guide
* Administration Guide
* Structure Guide
* Site Building Guide
* Theming Guide
* Developing for Drupal
* References
* Tutorials and Site Recipes

Faster list (14 words)
* Understanding Drupal
* Installation
* Administration
* Structure
* Site Building
* Theming
* Developing
* References
* Tutorials and Site Recipes

Am I driving you crazy yet?

leehunter’s picture

leehunter commented
Status: Active » Fixed

So I've done a quick and dirty job of the restructuring. There's still LOTS of work to be done fixing things like weighting and especially writing better overviews of guides and sections, and some content still needs to be moved around, but I think the major restructuring work is finished.

Despite the many rough spots, I'm pretty happy with the new structure. For the first time I feel like I can navigate the entire doc set with confidence.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.