[prev in list] [next in list] [prev in thread] [next in thread] 

List:       drupal-documentation
Subject:    [documentation] Future proof Drupal documentation structure proposal
From:       Thomas Svenson <thomas () nutshell ! nu>
Date:       2009-03-15 15:11:56
Message-ID: 49BD1ABC.3050303 () nutshell ! nu
[Download RAW message or body]

Hi all,

I have only been using Drupal for a few months, and just started to 
contribute back to the community with a little documentation and help 
for others who are new to Drupal.

The one thing that has been hardest to tackle for me is to find relevant 
information for the tasks I need to perform on my own Drupal sites. The 
current documentation is quite unstructured and it took me quite a while 
before I learned the best methods to use to find what I needed.

While this is still fresh for me I thought it would be a good idea to 
write down my thoughts about how this could be improved and restructured 
so it would be easier for both new Drupal users and more seasoned Drupal 
experts. What I have come up with is a more role based documentation 
structure that I think will make it easier to find what a user is 
looking for and that will be much more expandable and future proof.

My goal with this was to come up with one hierarchy that can be expanded 
as new versions are released as well as addressing the needs of both 
beginners and experienced users.

Top Level Categories
=====================
This is what will shown when clicking the Documentation link.

Getting Started with Drupal
----------------------------
This will only contain documentation and guides on how to download and 
install the currently supported versions of Drupal Core.

Site Administration
--------------------
Here you will find documentation for administration. This includes 
topics such as adding and configuration of modules, updating or 
upgrading, and user management.

Site Building
--------------
This category will contain everything about how build a Drupal site. 
This includes themes, creating content types, site structure, taxonomy 
and so on.

Content Editing
----------------
This sections is for those who will add content to the site. It will 
contain documentation such as how to use WYSIWYG editors and filling in 
forms.

Development
------------
Here all documentation on how to develop for Drupal is collected, both 
for Core and contributed modules.

Document Structure
===================
Looking at the documentation today, a lot cover several Drupal versions 
mixed in the same page. For a beginner this can be a quite big hurdle to 
filter, but it also makes it difficult to maintain as well as update 
when new versions are released.

Also, it does not make it easy for beginners or advanced users to be 
able to quickly find documentation targeted to their level and needs.

I believe some big benefits with my suggestion is that we will be able 
to have one document structure that will cover every version and any 
level of experience, as well as being much easier to maintain.

Version Tabs
-------------
I like the way I can filter modules based on the Drupal version for a 
site and I think this can be reused for documentation as well.

I would like that each page has two sections. The top section is a short 
general information that is for every version of Drupal. The bottom 
section is tabs with one tab for each major version + an optional 
Current tab.

The Current tab is used if the information for 5.x and 6.x is exactly 
the same. If there are any differences between 5.x and 6.x then those 
will then be in separate tabs and there will be no Current tab.

Each tab will have complete information so the user doesn't have to 
first read the 5.x and then the 6.x to see the difference.

When a new major version is released and there are difference, it will 
be very simple to add that information:

- Click on "Add version specific tab"
- If there is a Current tab, set what version(s) it is for
- Set the version for which the new tab is for
- The content editor will be pre-loaded with the content from the tab 
that was forked
- Edit the content by removing irrelevant information and add the new

Beginner / Advanced
--------------------
As I was updating Drupal for the first time I tried to search for good 
documentation, but I only found bits and pieces here and there. Based on 
that I created "HowTo: Updating Drupal 6.x to newer minor version", 
http://drupal.org/node/390448. For a beginner that HowTo is useful as it 
contains all needed information on one page, as well as explanations to 
why and how. For an advanced user though it contains too much information.

My suggestion here is simply to have a sub tab for each version, one 
Beginner and one Advanced. When selecting Beginner you would get the 
above HowTo, but when selecting Advanced you will get a much shorter 
version where all the extra content aimed for beginners is taken out.

Preferable both are based on the same content structure as you could 
then easily switch between them when needed. Then it will also be easy 
to first create the Advanced and then simply use that as base for the 
Beginner and fill in the blanks.


Documentation Defaults
=======================
The Documentation section will remember the Drupal version and 
Beginner/Advanced tabs so that when I click on a link to another page 
they will be used as default view values.


Content Types & Filtering
==========================
There are many ways of creating documentation. It can be everything from 
reference texts, HowTo's, tutorials, videos and so on. I believe it will 
be quite easy to fit them all in the the structure I have outlined above.

When creating a new piece of documentation there needs to be more 
taxonomy options to set. Some are set automatically when the page is 
added (as described above) and some are set manually.

I propose something like:
- Media Type
  - Document
  - Video
- Type
  - Reference
  - HowTo
  - Tutorial
- Drupal version
- Beginner/Advanced

It would then be very nice if it was possible to filter in search so I 
for example can click a checkbox that I only want to get search results 
for HowTo documents for the key words or phrases.


Related Content
================
For each page it should be easy to add links to related content. If 
someone, for example, creates a video that is based on my update HowTo, 
then a link to it, and wise verse, from the HowTo will be available.


Oki, I hope you like my proposal and that some of it can be used to 
improve the Drupal documentation.

/thomas
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/
[prev in list] [next in list] [prev in thread] [next in thread]