[documentation] Moving directory

[Lee Hunter]

I agree that there are different needs, different approaches to
learning, and different valid conceptions of what an ideal structure
might be. Added to that there is the complication that a single page
of the documentation might contain information that is relevant to
several different areas (a page might touch on theming, development,
and snippets).

That's why I wrote a few weeks ago that a hierarchical tagging
approach, similar to Wikipedia categories, along with the Faceted
Search module might be very useful in that it would allow us to create
multiple pathways. You could get to the same page from both the
theming track, the developing track or the "how to" track if it
happened to be relevant to all three.

Having said that, if we continue to use a standard heading/subheading
approach, the status quo is by far the most generally unhelpful model
because the headings do everything to obscure, and nothing to reveal,
the underlying content. They also tend to encourage the duplication of
content and they make it nearly impossible to find everything related
to a particular subject.

Lee Hunter
Senior Technical Editor


On Sun, Oct 12, 2008 at 12:07 PM, Ryan Cross <drupal at ryancross.com> wrote:
> The real problem is that you need to address the documentation on several
> different levels.
>
> - Topical
> - Type (learning style, audience, etc)
> - Version (especially important as we continue to expand our maintenance of
> more versions)
> - (and potentially quality, completeness, etc)
>
> Plus, not everyone goes to the documentation for a specific question /
> reference which requires good random/non-sequential access. Other people
> also want to be able to read documentation in a logical sequential order.
>
> Throughout my experience with Drupal I have found need to locate
> documentation on all these levels.
>
>
>
> On Mon, Oct 13, 2008 at 2:55 AM, Emma Jane Hogbin <emmajane at xtrinsic.com>
> wrote:
>>
>> Lee Hunter wrote:
>> > "Theme Guide" works well as a heading because it's clear that I'm
>> > going to find information about theming. On the other hand, "Howto",
>> > "Tutorial", "FAQ", "Best Practices" etc are all poor headings because
>> > they are so vague and meaningless that they can, and do, address any
>> > topic under the sun including theming, installation, hosting,
>> > development, using modules, etc.
>>
>> I have to throw in my +1 here. I have a strong dislike for documentation
>> that is sorted by "type" of documentation rather than "content" of
>> documentation. Of course if there was a link at the bottom of the page
>> that said, "see this as a ____ format ____" for different learning
>> styles that would be super awesome.
>>
>>
>> regards,
>> emma
>>
>> --
>> Emma Jane Hogbin, B.Sc.
>> Founder, xtrinsic
>> phone: (519) 371-2665
>> web: www.xtrinsic.com
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>