Documentation - challenges and the future

By sepeck on 3 Sep 2007 at 08:41 UTC

Drupal has a substantial amount of good documentation; the documented code as seen on api.drupal.org, the developers handbook and even the installation and configuration guide has lots of good stuff in it. It also has older stuff that doesn't get updated in a timely manner and can be confusing. The last major handbook re-organization was Jan 2006 and that was a substantial improvement. Currently, just the three main books would be over 1,400 pages printed out.

One of Drupal's strengths also leads to it's frustrations. Drupal is flexible, it is content centric, so you can accomplish a given task in multiple ways. This is something that can be very hard to have people find the time to document. For those who haven't spent time writing HowTo documentation, it takes a lot longer than one would first think.

So, the problem, long term sustainable documentation with Drupal is difficult. Drupal core moves and changes with each version. For many versions, most of these changes resulted in only minor cosmetic differences in the user interface and menu placement.

With the release of Drupal 5, these user interface differences becomes rather substantial. JQuery's addition to Drupal in version 5 actually expands the UI possibilities in even more ways. With Drupal 6 we will see more interface and additions to core capabilities.

So what to do? At the Yahoo OSCMS I discussed this with a lot of people and came up with a new plan for the direction of some of the documentation and have been working on it since. For an identified base documentation we will use DocBook v5, commit it to CVS and version per Drupal release and generate PDF's in addition to having it live online in the handbook.

DocBook!? Doesn't that raise the level of difficulty to contribute? Yes and no. Yes in that DocBook will be required for this core set of docs and updates to it will be treated like Drupal core updates, very few will have rights to commit to it and it will remain focused on that. No, in that this will not cover every scenario and there will still be a strong need for continued community contributed documentation that can be more specific to various scenarios. The handbook will be re-organized some to accommodate this, the end result is still being worked out but will be coming to a handbook near you soon.

This documentation will be a select core set of docs based on an expansion of existing documentation. I have added significantly to the install and configuration steps (yes, including screen shots). In addition to the existing documentation there are some Drupal concepts that get repeated questions and are not obvious. Articles written by members (I can coerce) will be included in a reference section at the end. If they are not updated or relevant, they will be removed from the next version.

The core around these docs will be expansion on the;

INSTALL.txt
- INSTALL.mysql.txt
- INSTALL.pgsql.txt
UPGRADE.txt
Default "Welcome to Drupal" instructions you get when you install your site
Existing module help text

These will be fitted into a basic framework

An introduction to the Drupal project (These documents will be available in PDF for download and this stuff is important and often asked in the forums)
Before you start. Requirements, terminology, basic best practices.
Installation. Expands on the install.txt and includes a basic configuration set for new sites with pretty pictures
Basic content management. Various basic methods to post content, create menu's with just Drupal core.
Administration. This is primarily every Drupal menu option if all your core modules were turned on.
Upgrading your site. From the upgrade.txt
Concepts. These are various collected articles on various Drupal concepts that can help new people to better leverage their new site. This section is transitory per version. If an article isn't updated or relavant, it won't be included in the next version.

I want to note, this is not a finished set of docs (I'd say almost alpha, almost beta). It still needs some editing, I have some feedback that isn't incorporated in yet, one or two outstanding requests for articles, there are some ugly sentences in it and the PDF generation has a blank page or two. Overall, I believe this represents something that we can commit to updating when a new version of Drupal comes out. We may not make the release date of Drupal 6 this time around, but I believe we will be close.

And no I have not upload it to CVS, it's been a longer week than I had planned for but it'll get there any day now so enjoy the preview and I hope this is something that people can get excited about and support.

I dedicate this first round release to my wife. Without her allowing me the time to write this, it wouldn't have gotten done.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

Attachment	Size
getting-started.pdf	1.43 MB

Comments

Excellent work

BioALIEN commented 3 September 2007 at 09:52

Was taking a quick glance but ended up reading half of the document :)

Very nice work. I did spot a paragraph about Drupal's history repeated twice. Maybe a copy/paste error?

---
Dee
iScene Interactive :: iScene.eu

yep

sepeck commented 3 September 2007 at 17:06

Thanks. At 1am sometimes you grab the wrong file to post. Updated the file.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

Great work.

owahab commented 3 September 2007 at 10:20

I agree, the last two paragraphs in page 3 are one and the same.

I have a question: I thought that with the release of Drupal 4.7.6, Drupal does no longer support PHP less than 4.4.0 due to the session issue.

Great work Steven.

Translations

gaele commented 3 September 2007 at 12:50

Excellent work, Steven.

- Have you thought about how to support translations of this document? I would love to have this in my language (Dutch) and would be more than willing to help with the translation.
- A derivative - or simpler version - of this document could serve as end-user (i.e. non-admin) documentation.

should be posible.

sepeck commented 3 September 2007 at 18:40

Let me get the XML files into cvs. I will admit to not having thought about how to handle translation of this document on a larger scale which is silly. Let me look at how some other projects handle it and we'll see what we can do here. There is no reason not to do it if we have volunteers. This may change where I was going to upload it into CVS though.

I'll talk to the CVS maintainers and see what they think.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

Steven, this looks

dries commented 3 September 2007 at 17:51

Steven, this looks wonderful! I'm really glad to see this happen, so keep up the great work. :)

Excellent!

raspberryman commented 3 September 2007 at 18:12

Awesome, Steven! I could have really used this back in the beginning, and I am sure many people will benefit from this. Thanks!!

Numbering PDF

guidot commented 3 September 2007 at 20:52

First of all, this is really impressive!

I have a suggestion on how to number the pages in PDF-Documents:

Unlike you did in your sample, I'd prefer having "flat" Arabic numerals from the very first page (instead of Roman numerals for the table of contents). That would make the paging in the TOC consistent with what the PDF-Readers generate themself (at least KPDF and Adobe Reader 7 allways start with an arabic 1 AFAIK).

People then could use these flat numbers from the TOC to navigate with the PDF-reader's tools or to select which parts of the document to print, without the hassle of having to add an extra offset. What do you think?

Agree

dnewkerk commented 3 September 2007 at 21:50

Wanted to mention I agree with this, if it's possible. For example: since I didn't realize at first that the TOC items were clickable (which you might want to note in some way as well if possible, e.g. "In digital copies of this document, the Table of Contents items are links"), I referred to a page number of something I waned to go have a look at, scrolled down to that page number (gauged by the easier to see page numbers in Apple Preview or Adobe Reader, rather than trying to keep an eye on the printed page numbers that aren't visible at all times), and found that it had nothing to do with the topic I was looking for.

-- Dave

...

sepeck commented 4 September 2007 at 16:21

This is the conundrum. DocBook default style sheets and most standard technical PDF's follow the convention of 'print' books. In general this means that the TOC gets it's own numbering, generally in roman numeral or other format. Then the pages are valid when printed out. As this is the vast majority of how such PDF's are currently done we'll probably leave it at that. I will stick a note on my monitor to look around some more.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

Flat numbering; Getting odd/even right

gwideman commented 5 September 2007 at 10:11

I'll vote another +1 on ditching the roman numerals and going with straight numbering front to back. Just because others (and not all others) attempt to adopt the superficialities of print doesn't mean folks that are producing PDFs for use in Acrobat Reader have to do so. The main reason that "front matter" uses roman numerals in the first place is because printers didn't necessarily know how many pages would be needed in the front until after setting the body of a book. We don't have that problem so much any more...

Regardless, if you *do* stick with the roman numerals *please* use an even number of them so that arabic numbers start with 1 on a right-hand page. Failing to do that makes double-sided printing (two runs through the laser printer) a nightmare -- including hitting bugs in some versions of acrobat where it gets very confused about whether you are specing page range relative to the page numbers on the page or the page numbers from the beginning!

Other than that, er, nice job and carry on!

stylesheets

moshe weitzman commented 4 September 2007 at 00:02

lets work hard on a stylesheet that really makes this sizzle. we should use info boxes and code styling and captions and all the things that paper books nice.

Fantastic job!

steinmb commented 4 September 2007 at 05:24

First of all you have done a fantastic job!
Pls. keep us updated on how we can create multilanguage versions in the new system.

--
Stein Magne
Norway

@steinmb

oh yes.

sepeck commented 4 September 2007 at 16:17

I have some sketches and such already, however, content content content first. In some ways it's like a Drupal based site. You can get content up and organized so people can access the information but with a click of a few buttons you can change the theme. :)

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

What happens to the Old/Current handbooks

NaX commented 4 September 2007 at 07:36

It sounds like you have a clear plan for the future and it sounds great, but I would like to know what is going to happen to the old handbooks.

I don’t like loosing history even if it is out dated and old. So would it be possible for the old/current handbooks to be made available on a sub domain for public reference, or maybe as an archive on drupal.org.

Or am I jumping the gun here.

Love the PDF even if its not finished, I have already given it to some newbie’s I have been teaching about drupal.

re-org the existing docs mostly

sepeck commented 4 September 2007 at 18:26

As I said above, the need for further detailed / specific documentation is still there. In fact, in many ways stronger then ever. I deliberately did not cover many scenarios so that we'd have something sustainable between versions where we would not be relying to much on third party versions of software.

I have a partially completed email that I am writing for the documentation list on a proposed re-org of the handbooks. It needs feedback, input and ideas. I have an idea for the over all structure which I believe will be well received but some of the details still need work.

Now, that said, some of the really old content will go away. Some has already been accounted for in other places in updates and such, others it's just old and confusing.

Oh yes, newbie feedback good.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

At the risk of complicating the issue...

adam_b commented 4 September 2007 at 08:16

There's a module at http://drupal.org/project/export_docbook which looks as if it could be helpful for this - but it appears to have been abandoned. Would this be helpful to allow people to submit documentation (which could then be checked in and controlled as necessary)?

I'm interested in this as I'd like to use Drupal to handle documentation for the company I work for - will be interested to see the final outcome.

API module

zeropaper

French

commented 4 September 2007 at 13:03

Yeah the API module rocks, i use it every day (on my localhost with the modules i often use and on http://api.drupal.org), it produces (if the source documentation fits the rules) a perfect documentation.
By the way, thanks to your wife, she let you do a really nice document ;) I wonder if it should not be packaged in a "start with Drupal" release!
If I found some time, and my girlfriend allows me to, I will probably translate it into french (by the way, if the source document as open-office doc was available, it would helps to do it).

version numbering

Eugene Dubois commented 4 September 2007 at 16:29

Great document. As a new drupal-user, it will be very important to me.

PDF's should have a version number though... could be a date or number, so we will know if there is a new version around.

- Eugene Dubois

...

sepeck commented 4 September 2007 at 18:04

DocBook has tags for noting version numbers and document history which will be added.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

Many kudos

forngren commented 4 September 2007 at 20:27

I don't think I can stop praising your work, but as always: issues are always easier to talk about.

I would like to raise the question about paths, while where at messing up the docs, why not give the docs path an overhaul? Now we have for instance drupal.org/patch which IMO should be drupal.org/docu/dev/patch or similar.

Again, THANK YOU.

Nice First Step

gareth_w commented 5 September 2007 at 05:52

Getting Drupal documentation in a printed format is a pain and the PDF is a great way to go.

My problem with Drupal docs is the documentation from the modules is patchy at best; some are covered extensively and others have barely a line or two. What I would like to see is a standard template that module devs could download and fill in so that there could at least be the same level of documentation for each module: basic usage cases, install & configuration instructions, a quick tutorial on using the most important features (and administrating them), etc. This would be a great help to a newcomer like me who is looking to do something more than straight out of the box uses.

Thanks!
Gareth

+1 on "a standard template that module devs could fill in"

Walt Esquivel commented 6 September 2007 at 05:19

Some of the contrib modules have extensive documentation and examples/demos, which I think is great, while other contrib modules have a very short description that leaves me wondering what I've just read.

I would like contrib modules to have better explanations so that folks like me can better understand exactly what itch the module's contributer was scratching. In the future, I'll take a look at what modules I'm using to see if I can contribute towards this worthwhile effort, but having a standard template would go a long ways toward getting us there.

And a BIG THANKS to Steven for all his contributions!

Walt Esquivel, MBA; MA; President, Wellness Corps; Captain, USMC (Veteran)
$50 Hosting Discount Helps Projects Needing Financing

There is an issue in the

add1sun commented 8 September 2007 at 20:26

There is an issue in the queue on this which resulted in the Drupal Module Documentation Recommendations handbook page. Still plenty of room for more work, so feel free to jump in. If you have a proposed template, that would be a great start.

Drupalize.Me, The best Drupal training, available all the time, anywhere!

A few suggestions

zirvap commented 5 September 2007 at 06:21

Very nice, well written and well organized!

A few suggestions that might make it even better:

Include how to install contrib modules (including new translations for modules) and new themes. This is vital info, and if the current descriptions are anything to go by, likely to change with different versions of Drupal
On the other hand: Parts of chapter 1 are more nice-to-know than really neccessary, and are not likely to change all that much, like the history and stuff about druplicon. These don't need to be in this kind of document, and are better placed somewhere else on drupal.org.
Include a short intro at the very beginning (chapter 0?) about what the intended scope of this document is. What kind of stuff is covered and (more imporantly) what's not covered, and where to look for more information. Yes, I saw the pointer to drupal.org/handbooks under Documentation and support, but I think it would be useful to have this more prominently placed. I'm guessing a lot of readers will skip chapter 1 and go straight to the meat. Perhaps such a link could be placed in a header or footer, if the DocBook format supports that

Added: Oh, and btw: I really liked those quotes, especially the one at the beginning of chapter 1 :-)

Good suggestions.

sepeck commented 5 September 2007 at 17:03

I already have a write up on how to install modules and themes, though I think I need to cover the multi-site stuff considerations with them better.... d'oh on translations for modules.

The stuff in part one is important for people to have exposure to and if they do skip it many will come back to it. These are often asked questions in the forums and if they print the docs out, chances are many will read it at some point. The online handbooks are about to be re-organized to account for this structure as well.

There is a docbook tag that covers an intro as you describe. I shall use it.

I have more quotes for the rest of the chapters :)

Someone told me to stop trying to make it perfect and just get it out for initial review. Some good feedback too that helps a lot in this thread so I am glad I did. Getting the CVS and projects setup and a nice style sheet to make the document pretty is my current hobby. Accounting for, or having available, this document in multiple languages is something I had not considered and something we've not had before. It's a good lead in for the next Drupal version and very exciting.

I am also going to rename it to: Drupal 5 - Getting Started. This being a more inclusive title of the content.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

Move documentation to docs.drupal.org

coupet commented 5 September 2007 at 20:17

Similar to api.drupal.org, it would be easier to reference and search.

----
Darly

...

sepeck commented 6 September 2007 at 16:34

Outside the scope of this discussion as restructuring drupal.org will be complicated. In addition you would lose all the integrated search with all the other site content and integrated user logon.

In the meantime, going to the search page and expanding the 'advanced search' fieldset you can narrow your search specifically to the book module. When searching the handbooks I do this manually. 'search words type:book' which accomplishes the same thing.

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide -|- Black Mountain}

-Steven Peck
---------
Test site, always start with a test site.
_{Drupal Best Practices Guide}

Thanks for the tip, I am

coupet commented 8 September 2007 at 01:07

Thanks for the tip, I am bookmarking the advanced search link as advised.

----
Darly

Great Work

mrgoltra commented 6 September 2007 at 17:26

Thank you, found out new things about Drupal.

Wow! Great work sepeck. This

v1nce commented 7 September 2007 at 17:33

Wow! Great work sepeck.

This is definitely a step in the right direction.
-----------------------------------------------------------------
Petafoo - We Love Animals

Groups Documentation

rmahon commented 6 October 2007 at 12:25

Steven
Very nice job, much needed.

If nobody else is working on it I would like to help with the groups documentation.
This is presently a can of worms. many modules some without even readme files.
conflicts between modules, database setups etc.

I have been using Drupal for several years and was part of the first documentation team several years ago.

I remember that Docbook was the subject of controversy. My feeling is that tool doesn't mater, since you took the lead you get to pick the tools. Just like a web site it's about content.

The release of you're effort also brings up the point that the sooner you get feed back the better the end product.

Nobody like to revise there work over and over, so early feed back is crucial success. (maybe at the chapter level)

Best Regards

Ron Mahon
http://The-villages-info-center.com
Yet another Drupal Site

Groups doc needed very much

clivesj commented 8 November 2007 at 13:31

Hello Ron,
wish I had your group-doc last week!
I was allready looking-up into installing OG but decided to go for it anyway.
All went well, and as I gained more confidence I started adding modules.
The last one was one too much. Then I suddenly remembered your remark here above about conflicting modules. In my case I think restricting access by role and OG group block visibility were biting each other.

The bad news is that I had to restore everything from a backup, and that's a tricky thinh to do, since the only clean way to abort OG is to disable it.

I have everything running again and want to attemp another OG-install. Do you by any chance have a draft of your OG-install-guide? If you want, I can update it as I go-along.
Thanks
Clivesj

Documentation - challenges and the future

Comments

New forum topics