Documentation lacks an information architecture

I think that this is sort of in line with part of the g.d.o thread here: http://groups.drupal.org/node/6568#comment-19577

This definitely has some hairy things that will need to be teased out but this same concept has been raised multiple times, especially by people who are outside of or new to the Drupal community. So, I think it has merit but at the end of the day, as always, it will require some elbow grease to actually come up with a plan that can be implemented and the the hours to make it happen. Unfortunately many ideas are simply not followed through on (I include my own postulating - I'm as guilty as anyone) and with changes of this scope it either needs to happen or not, halfway would make a worse nightmare.

So, basically if folks would really rock this and propose a solid plan for what the finished product should be and *how it would be accomplished* then I am all for listening and refining implementation.

At a glance there are some good ideas here. However, there are also some things we've tried before that didn't work out so well. Some of the things you've added to the scope are also things not necessarily "Drupal" responsibilities so if your ideas is an "introduction article" with links as opposed to "we're taking responsibility to document very complex situationally complex technological implementations" than that's a good thing I'd like to see.

My time is extremely limited for December (as in I am buried). With work, holiday/family and the soon to be released Drupal 6. So, I am going to proceed with my original thoughts on the /handbooks page overview organization for now to hold us over, but I'd like to seriously revisit this in January and map out your ideas with our experiences more to arrive at an overall better experience.

Keep in mind that part of my concern is maintaining a focused core set of documentation we write long term.

Some random thoughts in no particular order or relevance before I forget them...
Landing pages are important so yes.
-----Admin guide ---------
Missing Security mention. Security is part of administration.
Managing Servers - this seems more like managing sites.
Managing Server performance - more overview articles with links? The talent pool we have available and willing to write/maintain more complex documentation across versions is small.
Managing users vs Managing accounts/roles

-----Implementation guide---
Making content findable vs Organizing content vs Structuring your site - erg.....
Creating Communities - this seems more like a recipe, a large portion or Drupal sites are not community based but this is an important feature but seems out of place when contrasted with the rest of the items....
Blocks - configuring blocks also involves things specific to a given theme
Theme building is a subject on it's own due to the entire integration stuff. Once you get it then there is a need for how to manage stuff within your themes constraints. See http://drupal.org/node/171179 for the current D6 theme guide.

I am unclear on how you mean to embed "community advice" in the various sections. I'd be more likely to create dedicated forums for this part and perhaps collapse restructure the existing forums.

Again, these were random first thoughts as I read your outline and may not survive second thoughts, etc.

This is a great initiative. #2 most requested thing about Drupal (better docs).
http://groups.drupal.org/node/6636

I'd be wiling to lend a hand if this is being coordinated (couple hours a week). Some thoughts for the future:
(1) Build this into an initiative.
(a) Get steven on board. That would be key :)
(b) I'm willing to contact individuals that have expressed interest if we want to get some more hands.

(2) Consider completing this survey http://drupal.org/node/127285. Then we would have real data on who uses Drupal. Which is kinda important if you want to figure out what audiences you are trying to serve.

(3) I think a good starting point is to have audiences and their goals defined. Drupal isn't a commercial software project, but can learn a lot from that structure.

The website redesign process did some of this:
http://groups.drupal.org/drupal-org-redesign-analysis

Amazon posted what people are looking for. This thread defines the goals behind an information architecture for Drupal:
http://groups.drupal.org/node/6636#comment-19108

Past surveys have defined additional information:
- http://drupal.org/node/92304 (Administrator Survey)
- http://drupal.org/node/127285 (which would answer the core audience question)
- Dries never published the results of the state of drupal survey http://drupal.org/node/168976, but some are in his presentations:
http://buytaert.net/state-of-drupal-march-2007
http://www.flickr.com/photos/scatteredsunshine/page7/
(I've never been able to find the decks)

Core audiences (in my mind):
Developer (core). The core development community.
Developer (modules). Folks that build modules.
Developer (hacker). Folks that do more hobby-hacking, tinkering around the edges.
Developer (themers). These are the HTML/css guys... I think of them as developers, but they might be a separate creature.
Administrator (site building)
Administrator (site maintaining)
Administrator (Content/community manager)
End User

The thing that I think kills us most in trying to design for the community is the different skill/sophistication levels.
Low (I want to put up a website)
Medium (I'm building a custom online community myself)
High (I'm building a $100K online community with a company and a team)

Not sure how all this works itself into the information architecture, but willing to contribute a couple hours a week to move it forward.

I've been in the community a while and am unclear on the phrase 'build this into an initiative' as well. I tend to operate under the 'discuss, plan, then do' sort of guidelines.

From a documentation point of view, I found the survey not terribly useful. Dries survey came out right before the new 'getting started' docs were announced and released so the doc questions were immediately not relevant as they were answered before major doc changes were published.

I use the word initiative just as a description of the process of building some support and help as you discuss, plan, do. We're all saying the same thing :)

I really like the basic layout and content. I think that you zero in on the key problem "The current doc set contains an amazing amount of useful information but the many gems tend to disappear into the sprawling amorphous and inconsistent structure. With a bit of work I think the user would spend much less time wandering around in circles."

A good goal might be for those references to be broken out more from the docs. During a Drupal.org redesign, if those references were clearly broken out from the text, they could become structured (i.e. CCK node reference), allowing more people to make minor contributions (i.e. contribute a relevant link).

I really like the three categories: core help, contributed help, community resources. Again, in each of these areas, breaking out information in a more structured fashion would offer better "future proofing".

I also notice an issue from way back: http://drupal.org/node/57763. The handbook doc is not in sync with the internal help. What is noce about your format is that the main page + configuring for core can become the internal help text, everything else part of the menu.

[subscribe]

also, is this discussion still alive or is it continued elsewhere?

Changed the component to reflect the new component categorization. (DocSprint @Drupalcon Szeged 2008)

John
-----------------------

Drupal Norge
_{Det offisielle norske nettstedet for Drupal}

[subscribe]

While looking for a set of graphics to represent the various handbook organization ideas, I found this info with a lovely line at the end (emphasis added)

http://en.wikipedia.org/wiki/Software_documentation - about 2/3 the way down is this comment

There are three broad ways in which user documentation can be organized.

Tutorial
A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks.
Thematic
A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user.
List or Reference
The final type of organizing principle is one in which commands or tasks are simply listed alphabetically or logically grouped, often via cross-referenced indexes. This latter approach is of greater use to advanced users who know exactly what sort of information they are looking for.

A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two. (emphasis added)

While we may have different ways we want to organize the documentation (tutorial, version, theme, programming experience level, etc), I think the basic request in this thread boils down to there isn't ONE right way. Datamining the information needs to support both horizontal and vertical slicing and dicing. For example, horizontal (all version 6 docs no matter the intended audience or skill level) vs vertical (only API docs, only installation instructions - no matter what eversion).

Since we are generally bigots to what we learn first and feel most comfortable with, I dare say one person's facet solution is another's tag solution. I'd like a sandbox with 100 pages of docs and a way for the facet, tag, taxonomy, custom module, etc solutions that are envisioned to be activated so we could audition the different 'solutions'.

Please realize, I know not what I ask for nor the difficulty of it, just that I'd be willing to help orchestrate it.

I don't have enough information to say which ways are best.

#430456: Documentation structure as outlined in redesign mockups was marked a duplicate of this issue.

Marking as a concern of the Drupal.org Redesign project, but due to the enormity of the task, it won't be a requirement to launch. But we should try to put resources towards this as we can.

Yeah, just a note that this is being addressed in the recent Drupal Doc roadmap as the first priority item. Becca has begun work and also been in touch with Leisa about where the redesign left off and additional notes she had that never made it into the deliverables. I'm going to mark this postponed since it is being addressed in the roadmap plan now.