Drupal.org redesign – a strategy for the documentation section

Docs Home

Leisa Reichelt:15:36:39
ok. here’s the theory
Leisa Reichelt:15:36:49
drupal documentation is essentially like wikipedia
Leisa Reichelt:15:36:53
lots of pages
Leisa Reichelt:15:36:59
it’s not hierarchical
Leisa Reichelt:15:37:06
because it is grouped around so many things
Leisa Reichelt:15:37:14
so doing a hierarchical IA for it is nonsense
Leisa Reichelt:15:37:23
will only show how complex it is and where it is incomplete
Leisa Reichelt:15:37:25
which we want to avoid
Leisa Reichelt:15:37:30
hence our emphasis on search
Mark Boulton:15:37:32
yep – agree with that
Leisa Reichelt:15:37:44
ok, that’s the first part of the strategy
Leisa Reichelt:15:37:46
here’s the next
Leisa Reichelt:15:37:53
there are three key pathways to documentation content
Leisa Reichelt:15:38:01
1. i have a specific problem I need an answer to
Leisa Reichelt:15:38:05
in which case, i search
Leisa Reichelt:15:38:16
2. i’m new at drupal, or some aspect of drupal and I need to get up to speed
Leisa Reichelt:15:38:31
in which cse, i need access to some ‘designed’ content (eg. tutorials)
Leisa Reichelt:15:38:37
and I’m likely to hit the docs landing page
Leisa Reichelt:15:38:52
or 3. i need more information about <x> which I am looking at now
Leisa Reichelt:15:39:02
eg. I want to see the documentation associated with this module that I might choose
Leisa Reichelt:15:39:12
in which case, I want to see the documentation contextually linked
Leisa Reichelt:15:39:21
convincing so far?
Mark Boulton:15:39:27
Leisa Reichelt:15:39:30
Leisa Reichelt:15:39:38
so, pathway A is covered already
Leisa Reichelt:15:39:54
pathway C is also covered (although we’ll need to check for other places where contextual linking is appropriate)
Leisa Reichelt:15:40:02
pathway B is the tough one
Leisa Reichelt:15:40:13
because what *is* this section if we don’t have hierarchical navigation?
Leisa Reichelt:15:40:24
what do we have to draw inspiration from?
Leisa Reichelt:15:40:30
wikis, of course!
Leisa Reichelt:15:40:55
so, the sub navigation for docs becomes something like: docs home | API | Index | Recently Updated
Mark Boulton:15:41:03
makes a lot of sense
Leisa Reichelt:15:41:10
API needs to be kept separate I think
Leisa Reichelt:15:41:21
and we can play around with exactly how the INdex works
Leisa Reichelt:15:41:37
and then the landing page of docs is all for new people needing structured guidance
Leisa Reichelt:15:41:52
so it links off to whatever of this we have available
Mark Boulton:15:41:58
sort of orientation
Leisa Reichelt:15:42:00
including, I think, the recipes?
Leisa Reichelt:15:42:07
yes, indeed.
Mark Boulton:15:42:19
I like it – it solves the problem
Leisa Reichelt:15:42:24
and there are two main kinds of documentation pages
Mark Boulton:15:42:40
plus it gives the freedom to the community to tailor it to their needs as they evolve
Leisa Reichelt:15:42:43
the actual documentation, and then a more flexible ‘index’ template that people can use to group documentation in whichever way they like
Leisa Reichelt:15:42:52
Leisa Reichelt:15:43:16
and, it doesn’t make it look as though there is too much/too little documentation at a glance
Mark Boulton:15:43:28
exactly – the holes aren’t as visible
Leisa Reichelt:15:43:35
Leisa Reichelt:15:43:38
Mark Boulton:15:43:47
I might do a dance now
Mark Boulton:15:43:50
Leisa Reichelt:15:44:00

Docs - Article

20 thoughts on “Drupal.org redesign – a strategy for the documentation section

  1. wow that’s a bold start, the documentation not hierarchical? wikipedia is a fantastic piece of you know exactly what are you looking for, but otherwise, it’s totally unmanagable. I think hierarchy is good.

  2. I have to agree with chx. IMHO abandoning the hierarchical component of the browse use case is a huge mistake. It will only exacerbate users chief, and valid, complaint with the current handbooks– not being able to find anything.

    I’ve been doing technical documentation for a Long Time Now ™, and while wiki-style is good for non-technical documentation, I find it to be an unmitigated disaster for technical documentation. The requirements of good technical documentation are like no other type of documentation. Whether or not it’s presented hierarchically, there most definitely IS an inherent hierarchy. In other words, you simply will not understand point C if you haven’t seen points B and A first.

    The answer to fixing this problem is not designing a system that obfuscates it, but designing one that enables it to be overcome in spite of the collaborative nature of drupal documentation.

    One method would be to allow anyone to edit documentation, but only allow members of the documentation to place the pages in the hierarchy. There will also need to be an easy way to submit new pages for placement as well as request pages be moved.

    Another important component is getting the hierarchy correct in the first place. The current system of organizing pages by drupal version is a failure, in part, because items that don’t change from version to version don’t get referenced in the current documentation and users don’t know to look in the previous (“old”) version’s pages. There needs to be a simple way to designate version specific content while not organizing the hierarchy by version.

  3. Correct me if I’m wrong Leisa but hierarchy isn’t going to go away. There’ll still be main landing page for all documentation as well as sub-landing pages for individual module documentation and documentation on using major sub-systems of Drupal — form api, jquery, etc. As Leisa said, trying to fit all of Drupal into one hierarchy doesn’t make sense as there are many groups not just one.

    Also, when do you ever look at Wikipedia or Drupal documentation when you don’t know what you’re looking for?

  4. that’s right Kyle – there will still be hierarchy and navigation, but in much smaller chunks, rather than trying to fit it all into one structure which – believe me, I’ve given it a lot of thought – just doesn’t seem to work.

    I think there are two big reasons why findability in the current documentation/handbooks is poor now: 1. search is rubbish, and 2. the current hierarchy is not very helpful. For example, after all these weeks, I only just discovered ‘recipes’ in the past few days – these strike me as some of the potentially most useful content for people to get access to.

    From what I’ve heard and observed, most people *do* know what they are looking for when they go into documentation (they are cases (a) and (c) described in the conversation above). The main reason that people don’t know what they’re looking for is because they don’t actively have a problem that needs solving (other than perhaps, to get ‘up to speed’ with Drupal). The landing page of the documentation section will be completely tailored to them.

    Each ‘article’ of documentation should have it’s own contextual hierarchy of relevant/related pages, and next/previous pages where this is appropriate. Tutorials and other more ‘designed’ documentation experiences will also be available. And we will also be promoting contextual linking to documentation more throughout the site.

    At least, that’s what we’re thinking at the moment…. would love to hear more thoughts/feedback etc.

  5. update: I’ve just thrown a couple of very sketchy wireframes into the post above that may help make sense of the conversation (probably depends on how good you are at deciphering my scrawl). You can also disect these at the Flickr Group for the Redesign here: http://www.flickr.com/groups/drupalredesign

    this will also be incorporated into the next iteration release of the redesign, which is happening later this week, for you to take a look at.

  6. Yes, this layered approach is exactly what I’d like to see more of for the docs. Thank you also for keeping the API separate. (I use it differently.) Another suggestion that has come up is “see also” at the bottom of a documentation page, like php.net’s docs. http://ca3.php.net/manual/en/function.array-merge.php

    It might be interesting to have a content filter that looks for Drupal functions and links them at the bottom of the page (or wherever) to the API documentation.

  7. Information architecture is exactly what the Drupal documentation desperately needs. Replacing a very bad structure with no structure at all, would not be a step forward.

  8. Remember people. Information Architecture != hierarchies. Ask anyone if it’s easier to find information on the web via Google or on their intranet. The answer is virtually always on the web.

    Content that’s heavily interlinked and paired with a great search engine is much more browseable / findable than the simplistic “right” answer of a hierarchal structure. There are many ways of structuring information each one meeting different needs. I think the three-pronged approach Leisa suggested makes sense.

  9. The information architecture that Leisa is suggesting is not to remove the hierarchy, but to chunk it up into small, understandable and more fluent related lists.

    The rigid book structure is broken when you don’t have a master planner to determine where things go and how they make sense there. A more wikipedia style documentation is actually a very common tool used for software that requires community help for documenting functionality. Almost every open source software has some sort of forum and wiki doc site.

    Besides, if I’m reading the documentation about the Login Toboggin module, I’d like some contextual links to learn more about the user authentication system, wouldn’t you?

    Good job Leisa, you’re going in the right direction.


  10. Not either or, use both.

    Taxonomy needed to handle the multiple dimensions, Vocabulary=Classification factors (eg version applicability, “topic”)

    Hierarchy’s fine as long as you don’t mix classification factor – Topic’s appropriate. It breaks down when multiple Topics apply to a node and the hierarchy only allows a single location.

    I like the idea of a hierarchy of Topics, a node defining the Topic, clarifying the boundary edges, see also links etc. Then all nodes tagged with that topic showing below. A given module could be tagged with many terms. Allow the user to filter based on version applicability, stable vs dev-only, recency of last update, volume of issue queue, etc.

    And having good Search is critical, embarassing we all need to rely on site:drupal.org in Google, especially since Dries has Solr-based enhancements – IMO Drupal.org should be top of the list of Acquia demonstration “clients”.

    /end 2 cents

  11. If you find content via google, it might still be organised into multiple pages, chapters, or some other kind of hierarchy. I think we all know that one single book doesn’t work for organising the handbook as such – but smaller sub-sections are likely to keep their structure, at least initially.

    One good thing, is that Drupal 6’s book module allows you to have multiple books – so once we upgrade Drupal.org, it wouldn’t be much work to split all the ‘top level’ books out in to separate ones to get us started.

  12. I’m a “technical communicator” by trade (technical writer, documentation monkey, whatever…) and this looks great.

    Multiple entry points to cater for both the types of user and the types of information. Once ‘in’ the information the navigation is as hierarchical as can be presumed from the current context.

    You obviously learned a few things at the Online Help Conference in Edinburgh!! ;-)

    And, as someone else pointed out, since when were these things EVER either/or discussions? They are always ‘BOTH’.

  13. It’s definitely NOT an either / or discussion– we absolutely do need both. I perceived the original suggestions as recommending using only a wiki style documentation and completely abandoning hierarchy– which I still think is a mistake.

    And while searching is very much a sore spot and desperately needs to be improved, the chief complaint I see when providing support in the forums to real newbies (as opposed to developers who are just new to drupal) is that they simply can’t figure out how to get started. That reflects a complete failure of guided learning that randomly wandering around a wiki will not solve.

    Getting started is not done with search– it’s done with guided browsing/reading. How can you search for something when you have no clue what you’re looking for? This is particularly true of drupal where some of the jargon is completely unfamiliar to true newbies.

    We, as the knowledgeable community, need to guide real newbies through the topics they need to understand in the order in which they need to understand them. Once they have that basic foundation, THEN they can jump to a wiki style interaction where they will have specific needs they wish to find information on.

  14. @worldfallz – I couldn’t agree with you more. In fact, the need that newbies have for structured, handholding documentation is a big part of the rationale behind the strategy as I had hoped to outline in the conversation I’d posted.

    By allowing people who know what they’re looking for to search, we can then give over important pages like the Documentation landing page entirely to supporting newbies.

    I’ve also made an allowance for a special type of content, which I’ve called ‘designed content’ which is all about a more linear and structured pathway through content to support people who need this more scaffolded learning style.

    so, i can’t help but think, we’re actually on the same page with this.

    at any rate – the next iteration is going to be available in a few short hours I believe, so we can have a play with it there and see what we think.

    thanks again to everyone for such thoughtful feedback

  15. I like the IA plan overall, and I’m looking forward to having a place to start when I start learning drupal, since that is my plan. I’m curious, when you say that you don’t to show where the documentation is incomplete, where the holes are, I wonder whether that leaves people searching for something in vain, thinking they are searching incorrectly. Is there some way to highlight where the incomplete sections are that need community contributions, so people know if they have reached a dead end?

  16. Some random points ….
    .. Has the search function improved in the backend of drupal ?

    .. Drupal documentation, as it appeared to me, unlike the hype, was / is actually quite useful and structurally nicely laid , only thing people were/are jumping at the forum without really going through the docu.s even minimally –> perhaps a knowledge-base type thing that prompted a relevant link to a relevant pieces from the docu.s before a forum post or issue is submitted could help

    .. apart from ‘cardsorting’ and classification or non-classification of things ‘documentaion’ per se can be champion when the actual documentation follows or imbibes the details, including text and static images, describing things to such details that makes drupal books really redundant … till then there will be some or other ‘complaints’ of insufficiency of docu.s

  17. (Perhaps this is not the right thread)

    Modules should have a user’s manual section. Now modules have the documentation link, which is useless. The maintainer of the manual could be the module developer or someone else. Others could help in writing the manual by simply commenting the manual node. A demo site or at least a captured image(s) of what the module does, would be nice to get the main idea quickly. These could be added by others also.

    Themes should have a data sheet (in table form?). Comparison option of selected themes would be nice, but not necessary. At least a large captured image of a theme should be “mandatory”.

    These changes would be easy to make.

  18. Really enjoyed this post Leisa. I like your approach to documentation, and I also like your approach to collaborating with Mark. It’s got me thinking – for this project, were you typically communicating to Mark with verbal/chat along with lo-fi wireframes and sketches? You guys have been pretty fast with iterations, and your process have got me thinking. Would love to see a post on the project process in some more detail!

Comments are closed.