Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
By add1sun on
For the last few months myself and quite a few community members have been working on a larger vision for our beloved Drupal documentation. It has taken quite a bit longer than I had hoped, but I want to put out a draft of an initial "roadmap" for documentation that outlines our bigger issues and an approach to tackling them. I've attached a document which has everything we've hammered out so far in a 10 page document along with three appendices. This post is just a short summary of what is in that document and to let people know that we are gearing up to kick things off and really make Drupal documentation rock.
For starters, we've spent a lot of time identifying problem areas, prioritizing them and setting out some target dates. When looking at the tasks we need to accomplish we recognized that there are two main areas to focus on: the documentation itself and the community of people that create and maintain it.
Two main projects
The most important thing to put our energy into right now is to redefine the information architecture of our docs so that they are more usable. To that end, we are fortunate that Becca Scollan, who did the University of Baltimore usability testing, has offered her services to take on this crucial task. Becca will be leading the charge in this effort and we will be looking for help from all areas of the Drupal community to provide information, legwork and feedback to drive it forward. In the next few weeks we will be launching a "stakeholder interview" process where we will need community members to interview each other about their experiences with documentation. We'll add more information about this to the Content architecture section of the Community initiatives Docs roadmap.
The other initiative we are starting today is to improve the recognition of documentation efforts and find out better ways to communicate with and support people who want to help. There is a short survey posted at http://docs.drupaltest.org that we'd love to have everyone fill out so we can start important conversations about how to recognize the people behind the docs.
Communication
Speaking of conversations, this isn't something that can be successfully pushed forward by just a handful of people. The documentation is a community resource and we all owe it to ourselves to invest in making it better. Everyone is encouraged to be part of this process. make your voice be heard and get your ideas out there. The main channels for communication we will be using are those that are familiar to our community. We will use the documentation mailing list for discussions and hashing out plans, while we use the documentation issue queue for our tasks. To have a central place to organize some of these tasks, we will make use of the Community initiatives section of Drupal.org, much like Drupal core has. There is a Documentation roadmap section where we can create "landing" pages for folks interested in working on particular areas.
There is an IRC meeting in #drupal-docs on the Freenode network scheduled for Tuesday, June 16 at 17:00 GMT 18:00 GMT (darn it, sorry, this should be 18, not 17). The meeting will be an open time to discuss the roadmap, ask questions and start organizing things. Feel free to drop by and join the conversation.
We will make announcements about new work and calls for help on the mailing list and on the Documentation team group page, which you can follow with RSS. Please join in and be part of making Drupal documentation the best it can be and serve all of us better.
| Attachment | Size |
|---|---|
| docsroadmap-final.pdf | 317.39 KB |
| roadmap-AppendixA-docs-tasks.pdf | 153.15 KB |
| roadmap-AppendixB-outreach-tasks.pdf | 151.27 KB |
| AppendixC-drupaldocs-mindmap.pdf | 654.14 KB |
Comments
Clutter
Hi there folk,
Im new to drupal and have been contemplating drupal vs joomla, I have been made to believe that drupal is the stronger option, I would like as a new user less clutter, when an individual first encounters you site they are struck by a rich mix of information. Though this isn't bad I think its not clear cut for instance as I right this I have been struggling with an installing of drupal on my computer which runs Kubuntu. Im sure the information is around some where but thirty minutes on and I can't seem to find it. my advice get rid of the clutter, better category management, and pdf versions of the documentation for those of us stuck without a permanent internet connection.
regards
Buyongo
=-=
with regards to installation, there is an install.txt file in the download. Is that not helping? if not: How can that file be improved?
Let's discuss improving the install.txt in a documentation issue, with your desired alterations.
Make INSTALL.txt easier to find
Making install easier is not just about improving the content of INSTALL.txt but making it more obvious that is the file that has the install instructions (It sounded like this Buyongo spent 30 minutes looking around for instructions, not 30 minutes trying to understand INSTALL.txt). It wouldn't hurt to format the file a little better with some headings and anchor links, people expect more polish then just plain text now days.
Here are some suggestions.
1. Most new folks want a link to install instructions on the same page they download an application from. It is very Unix like to expect folks to uncompress a software package and then go looking for a file called INSTALL.txt (or README.txt). I remember when I first installed Drupal I at first thought this file was used by the Install program in some way. I had no idea it was the install instructions just by looking at the name.
2. Why do the install instructions need to be in a plain text file? Why not make them html format as in INSTALL.html? It will make them easier to follow and would support a more useful and friendly look.
In summary put a link to a Installation instructions page on these locations
http://drupal.org/project/drupal
http://drupal.org/drupal-6.12
http://drupal.org/
This page could give links to the latest version of INSTALL.html and could start with a paragraph that mentions something like:
1. Download Drupal
2. Follow the Installation instructions found in INSTALL.html found in top of the Drupal directory you just downloaded.
3. For additional help please refer to .... (handbook pages on install?)
=-=
good suggestions. Which should have issues created for them. Some of the suggestions in your comments are related to the drupal.org redesign.
ugh
Personally I hate when software doesn't have an INSTALL or README in the tarball that is accurate. I hate having to load up lynx in a terminal (or browse through directories in firefox to open a local file) just to read installation instructions.
less INSTALL.txtis so much easier. That or double-clicking and reading INSTALL.txt if you're in windows.Seems to me that something
Seems to me that something like this could fix the issue:
http://img81.imageshack.us/img81/5673/newukr.jpg
enters a newbie guide that will take you through the process of setting up drupal and onto learning more via the handbooks section (as well as how to use the handbooks section)
New user guide...
I believe it would be useful to new users if we provide a "new user guide" very prominently on the main Drupal.org page. It should be no more than one or two pages. Very concise. There is far too much information available to new users, and this makes it confusing. Even better if it could be downloaded as PDF to print for later.
Is our goal to provide documentation for the "geek" or for the project manager, marketing person, and executive who needs a solution without the clutter? Perhaps both, and it may be more realistic to get some people involved who aren't so involved with Drupal's code to write some non-technical documentation. Any other technical writers out there who aren't Drupal-coding guru's? I'd like to help too.
@Quevin — Sr. Technical PM
=-=
you are already in a position to help. Documentation pages can be created by all registered users on drupal.org.
I doubt you will be able to confine to two pages. The drupal cookbook was written by a new user for new users and is the best documentation I've seen for new users in the documentation area.
There is an abundance of work going on with regards to documentation. I am sure the documentation team would love to hear from you. However, this acts as notification and provides the information needed for those commenting to get involved.
I know what beginners need
Hello,
I started with Drupal 6 months ago. At the time I was as confused as any beginner is with Drupal. I can relate to all the issues many others have posted above. I am not a programmer. I do not know anything except HTML.
Even I was thinking of going to Joomla. The trade off was simple for me. It would take a lot of time to learn Drupal (only way that I had was trial and error, and then getting used to).
But then I found the solution. It was Basic Drupal tutorial by Lynda.com: http://www.lynda.com/home/DisplayCourse.aspx?lpk2=620
This video is what every newbie wants. It explains the basic fundas on which Drupal runs. It lays down some techniques which advanced Drupal users take for granted (like install instructions are always in install.txt, how to decide whether to use a module or not, external resources like drupalmodules.com, etc. etc.)
It covers very basic things like what is a node, installing drupal on wamp/mamp/lamp (I didn't know what a development environment was before watching this video), how does navigation work, what is a block, even how to use Drupal.org, what to do when Drupal.org's search bar is not available, etc.
I think we need this kind of documentation. Of course now we cannot publish the transcript of this video (although that would be great for beginners).
Website or documentation problem.
I have a lot of sympathy with the views above. I started using Drupal 18 months ago. I can still remember having difficulty finding my way around the site. Although I have progressed beyond this, nothing seems to have changed. I suspect that once you make the leap you stop noticing this early difficulty. There needs to be a very clear section for newbies on the front page with 2 entries:
- What Drupal does
- First steps in doing it
Perhaps more experienced users could bookmark a different page for jumping off to sections more of interest to them.
The documentation itself is enormous and really could do with a content management system to organise it!
"The general roadmappy overview goes here. Basically, kick butt."
Yup good start!
Basically in Agreement
I basically agree with the above points raised... plus, I think having a CMS site to organize the CMS documentation is a capital idea!
However, I'd also like to point out that a searchable database with keywords does work pretty well, too... what I'm thinking is, having a portion of the admin section in Drupal (not sure if this would be easier as just a database node or as a full-fledged module) which can pull directly from drupal.org's documentation docs, reformatting for the individual site. This isn't really direct database access, but rather an API which can pull the information resources transparently, and which checks prior to the search for connectivity.
Additionally, a .chm help file and .html dumps of the entire documentation (similar to what other FOSS sites such as PHP.net are doing) might also have some utility.
Food for thought!
A large part of Drupal
A large part of Drupal documentation is inside Project issues, and streamlining those should be a goal as well.
For example, if Drupal.org could leverage some of Drupal's power like installing the flag module, so users can subscribe to a post without having to add a "subscribing" or "subs" comment to it would be nice. Some issue posts have 40%-50% "subs" comments.
I found a feature request for this as well
http://drupal.org/node/357290
My Drupal sites:
=-=
odd thing is, that all users can subscribe to issues (and have had this ability for as long as I can remember in the issue queue) and yet, they still do the subscribe thing in comments. Once inside a project there is a subscribe link at the top of the page that allows you to subscribe to your own issues, all issues and the like for each and ever project. Granted the link doesn't jump out and bite anyone but it is indeed there.
Documentation
I am replying as this seems to be the only option as opposed to just making an additional comment...
Based on my more pleasant experiences with installations, when I download a new program I would like to see a readme.txt file, the same in an html version, and also a link to the drupal site with same information. Of course, all 3 must be concurrent/identical. This gives the immediate impression that someone has taken the time to simplify the process for me. Perhaps the html pages shoud be called 'getting started' and should be foolproof with respect to installation. A brief tutorial that guides you to install a module with some interesting but basic functionality, such as a recipie book, would seal the deal.
I just checked that but you
I just checked that but you only have to options:
Own Issues, or All issues.
the problem with this is that it is not atomic. I dont want to subscribe to all issues, or I may not have any issues I started myself :) But sometimes I am curious of others, and maybe only one issue for that project
My Drupal sites:
exactly. so I have to comment
exactly.
so I have to comment to get subscribed to this issue, or I can subscribe to all Drupal issues.
Not helpful.
_
FYI to all concerned with the 'subscribe' issue:
http://3281d.com/2009/03/27/death-to-subscribe-comments
Comment
Yes, I found the comment link (at the top of the page where of course I did not see it as I was at the bottom of the page)
Thank goodness
I'm glad this is becoming an increasing priority. For those of us who aren't code-nerds or serious techies but enjoy building Drupal sites, the lack of decent documentation has been a serious bugbear.
Not quite sure what I could to help but am happy to suggest that the documentation should be written in plain English (as much as possible) for the benefit of non-experts.
Thanks,
Karl
http://www.networkingclubs.co.uk
Database documentation?
Will you be providing documentation for the tables in the drupal database? E.g. what tables/fields are used when a node is added?
How to through to issue
Current documentation often does not connect to issues and occasionally something is removed from documentation because it is fixed. Both could use examples for documentation creators to follow in a common format.
If a problem exists in Drupal 6.10 and is fixed in 6.12, should the documentation mention the problem? I think the documentation could start with something like "Updated for 6.12" and have a "Issues for earlier releases" list at the bottom. People with older releases are reminded to upgrade before using a specific feature.
Yesterday I battled with an Input formats problem related to the Line break converter and blockquote. That type of problem tricks a lot of people. The issue to repair the problem hangs around. Surely all documentation to do with input formats and content formats should mention the issue with an example of the problem and mention of any release that fixes or reduces the problem.
petermoulding.com/web_architect
Filter by version
When I search through modules on Drupal.org I always filter my search by the version of Drupal I'm using. Drupal's online documantation should provide this same functionality. I can't tell you how may times I've come across a tutorial or code snippet that sounds like the answer to my prayers, but when I click on the link I find out it's for Drupal 4.7. This makes finding useful information much more difficult.
––
Jeremy Stoller
Senior Graphic Artist
California Science Center
Newbie in all respects of the word
I'm a marketer, not a developer (although I'm technically adept, I wouldn't know PHP from a hole in the wall) and I have been playing with Drupal for 2 weeks straight now. I have to say that if I didn't stumble upon Acquia Drupal and their INCREDIBLY easy installation process, I don't think I would be half as far as I am today (I'm actually pretty amazed at how far I've gotten). The biggest stumbling blocks I've encountered thus far is the incredible lack of documentation on all of the contributed modules out there. Some don't have any at all. Others, even the really established ones like, are really lacking instructions on how to use it, let alone use it to its fullest. It's taken me 10-12 hours to figure out some pretty mundane things.
Anyway, I'm all for better documentation. I would look at Acquia Drupal as a good place to start. They seem to really get it.
Start a documentation page
I used to battle with undocumented modules by keeping notes then posting in the forum or an issue when I ran into a problem. Recently I started using a new approach for a couple of modules. I created documentation pages for them. Marked them as needing updating and just added whatever I found while experimenting with the modules. Other people started adding stuff. People fixed the spelling mustakes and made the grammar proper like. I find it almost as easy to keep notes about module installation in the Drupal documentation pages as it is to maintain an Abiword document and far more organised than a row of stick notes down the side of my screen.
petermoulding.com/web_architect
=-=
:applause: ^5 you certainly seem to get it!
Blame it on those postit notes
I changed my approach when the weight of the yellow sticky notes made my monitor fall of the desk and crash through the floor into the apartment below where it knocked their frypan over, starting a fire that swept through three city blocks and set fire to a news helicopter flying overhead which, unfortunately, crashed into the hospital killing hundreds of people. Then the really bad thing happened, I lost broadband access.
petermoulding.com/web_architect
=-=
lol.
If new users only took the time to understand how valuable they are to the documentation process. Sure they may not know everything about a module or a feature but they could kick start the process and others can add to it. Living documents can grow and be fruitful.
_
Yes... applause and bravo!
This is a great example of how to contribute! WTG.
Belated thanks
I can't believe I missed seeing this post for two weeks! Blame it on the bossa nova... and moving cross-country.
Thanks for exploring *how* people contribute to documentation in useful ways. Confusion about that process has stopped me more than once. But I'm optimistic!
---
Tom Geller * tomgeller.com * Oberlin, Ohio
See my lynda.com videos about Drupal
Suggestion
I made a suggestion here:
http://drupal.org/node/503874
a couple of days ago.
Please take a look.
I had been active on the
I had been active on the Drupal doc mailing list several years ago, but then fell away from Drupal for a few years. A project recently came my way that brought me back, and I must say, I'm really impressed with how much improvement there is in the Drupal documentation. The core documentation is more complete, with better writing. The search mechanism, though still far from ideal, is usable - something that wasn't true back then. I don't remember all the structural details, but I do remember being frustrated by navigating the docs - something I don't feel now.
I'm glad to see that the documentation is still getting significant effort and attention. Don't let any current problems or criticisms detract from all the work that's gone into it over the years, with a fair bit of success in my opinion. The contributed modules as a whole are always going to be weaker than the core; that's the nature of the beast. Installation will likely never be as simple as installing Microsoft FrontPage. There will always be users with differing expectations that go unmet. But the people-oriented approach in the road map is a good formula for continual improvement and success.
Please take a look at this example
CodeIgniter is known for having an exceptionally good documentation package, to the point where many people new to PHP frameworks will select CodeIgniter over Zend or CakePHP, simply due to the documentation.
CodeIgniter has one central starting point to its documentation, which in IMHO is a good thing to have, so I would suggest something similar is maybe used for Drupal documentation:
http://codeigniter.com/user_guide/toc.html
Documentation that assumes you already know how to do it
I've recently started using Drupal (welcome to my first post) and my biggest frustration with the documentation has been the number of occasions when it assumes that I already know how to do the activity being documented. The one that jumps to mind is when I was trying to figure out how to install my first module and everywhere I looked the answer was "install the module in the usual way". Perhaps issues as basic as this just need their own page to which developers can link.
This raises another point which has been touched on in an earlier post. Many module/theme developers seem to feel that the job is done when the module/theme is developed rather than when it is developed and documented. If Drupal has a set of documentation guidelines for developers to advise them on minimum documentation standards, they're not being observed. Just a checklist of headings would be a great start. The vast number of excellent modules and themes is a key strength of Drupal so the inadequacy of their documentation is a key weakness.
The other experience I've had is the general technicality of the material. For example, I just downloaded the Drupal 6.13 update and read the install.txt. It says:
Move the contents of that directory into a directory within
your web server's document root or your public HTML directory:
mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html
That might be good if I was using Unix but I'm using Windows as my development environment. I may be wrong but I think if I were to use a Windows cut and paste to do the equivalent thing to a mv (move?), my site would be clobbered. Don't worry, I'll figure it out but it will take me (and all those like me) hours of time that a few extra minutes by the documenter would have avoided.
Documentation by experienced people
Hello Clarenza,
Much of the documentation is by experienced people. We need first timers contributing their questions and notes. On occasions we get answers to
A person might know how to drive a car and might know about fire but that does not mean they know how to start and drive a steam operated car (steam cars were common before petrol cars). The same happens when a Windows user has problems with weird Unix permissions or a Linux user, already used to thousands distributions of Linux cannot understand the slight variations between Windows versions. Something really simple, to me, could stop you from completing an important task. Instead of me documenting that task as , I should be remembering back to last century when I was a kid trying to install FreeBSD in my first Tonka truck and had the same problems.
I am a great fan of links with titles and examples. If I write something that is an acronym, I like to link to a page explaining the acronym. On one page I gave detailed examples and the comments were full of . The examples were built based on beginners first posting comments about . We need that feedback.
The documentation is only just started spelling out things step by step. The documentation has only just started adding the Windows examples where Windows is different to Linux/Unix. The documentation has only just started to show the Cpanel versions of the stuff that ancient creatures do with their DOS/Unix command line box.
Keep asking your questions. If the answer does not match your expertise, flash your L plate at them. Explain your background or current level of knowledge then ask again.
Peter
petermoulding.com/web_architect
Minimum documentation for themes and modules
Wow! This discussion seems to be heating up, and what a welcome it is for me, I'm very new to the open source environment, got my kubuntu up and running with a bit of fuss then my drupal install was hell, that said modules and themes are a headache and then when you search for an answer there's that thing about checking if some one has posted something similar, the amount of knowledge in forum posts is alot but often it answers only a part of your question and not the whole, well maybe for me anyways, is there a way we can channel some of that information it documentation, then a minimum requirement for module and theme developers should be understandable documentation on the module or theme and maybe an example of usage especially for module, most of the modules tell you what it does and thats it, but key achieving anything lies in implementation, also if possible why not use the advanced help module and example module to link to documentation that can be downloadable for practical examples on a particular module no more mucking about trying to search and find, then for someone like me who's new to the web design and development, things like css are mind boggling im sure I'll get around to understanding it but it would be good if someone had put together an idiots guide to css using drupal. Just a thought.
Buyout
You can start something
See http://drupal.org/node/488070#comment-1740056. If there is nothing that fits what you require, start a discussion in a forum. When there is enough info in the forum topic, start a documentation page. In the past a lot of people thought there should be one page for each topic. Now we are starting to see beginners pages separate from advanced pages. We just need the beginners to ask the questions that experienced users forget to include in the documentation. When you want to set a specific file permission for one user, the way you do it is totally different from operating system to operating system and from file system to file system. In some combination's, I have many years experience while in others I have less experience than a recently fertilized egg. If I was to document Linux ACL for Drupal, it would be The Little Golden Book of ACL or My First ACL Reader.
I think one significant reason for some current documentation pages running aground is that they do not describe the target audience for the documentation then people try to make the page fit everyone. The pages become too long for some people and not detailed enough for others. If you create a page with lots of explanations, someone will post a comment along the lines of
petermoulding.com/web_architect
If we include tags for
If we include tags for 'windows steps', 'linux steps', 'tips', etc... then we can create content that the user can toggle by clicking a button or something. For example if they are browsing a documentation page it will contain a simple set of steps to complete a task, and every step can be expanded upon in the relevant areas by the end user toggling the appropriate information.
This has the advantage of all the information being in the one place, and giving a tailored approach to learning for each user.
I started using open source
I started using open source software about 2 years ago with Joomla and despite the shortcomings of Drupal documentation I have to say that it is light years ahead of Joomla documentation. I am an "older" user who is very new to Drupal. I installed it for the first time about 2 weeks ago and plan to launch my first site next week. I think that my experience with Joomla helped me a good bit in learning the basics of Drupal but I agree there is a need for a short beginner's guide.
I will have to go back and re-read this discussion to see how I can help.
Durpal is a great platform and I am really looking forward to being a part of the community.
Finding the right module
My personal grief with the Drupal documentation (I'm a techie anyway so I handled installation without too many problems :) ) is trying to find suitable modules and to browse through them.
The granularity of the module classification needs serious improvement - 300+ entries in the Administration section, 400+ entries in the Content display section doesn't narrow down the search a lot. Perhaps a set of keywords (preferebly from a defined list of keywords) should be awarded to each module. Then a filtering function à la del.icio.us so that I could (say) filter by 'content display' and then by 'multimedia' etc. through the defined keyword list.
Again with so many modules there is significant duplication so it's then difficult to make a choice between similar modules. Having a found a sub-set of modules I'd then like to be able to filter by popularity, activity etc. in an attempt to find a particular module which is well-used and well-supported (mainly so that I can be fairly confident that it'll be upgraded to Drupal 7).
Being able to easily browse the available modules would also be handy - how many people have come across a module (while looking for something else) and thought "I didn't know that module existed - I've just wasted weeks programming this and I could have just downloaded and installed x in 10 minutes."?
doesn't the download search
doesn't the download search take care of most of your concerns here? I find it extremely convenient to use.
=-=
and don't forget about drupalmodules.com
I noticed one issue with the
I noticed one issue with the download / modules search, namely it loses the search term when you sort , be it usage stat, creation date etc.
My Drupal sites:
the most important group are
the most important group are advanced php developers ...
they are totally forgotten. everybody says: have a look into the api - but you need a better overview in the general concepts and important functions.
so, ideal would be something like an "commented api".
.
just have to stick my nose in here,, The developers are the best crowd ever found in one place!
The community is top shelf and even if the documentation is not a shiny piece of priceless gold.. This is still the coolest place on the web!.
there, i said my 3cents worth. and after a year around here, i could write a full page. lol
and verymisunderstood is a great member of this community! He has helped Everyone!
glad to be here.
Yep, I second that,
Yep, I second that, Verymisunderstood has helped me kindly thousand times.
My Drupal sites:
Yebo! Here's to drupal!
Being new to drupal is great! Dont get me wrong its been over 5 weeks since first download and the initial frustration, then skimming through module after module to find what I need, then finding some thing that actually does the job, mind you I have never developed a site till I started with joomla!, yes joomla, but for some reason it couldn't install on my webserver so drupal was next on the fantastico list and thats how I found myself here, 1 thing I should point out is though I ended up here by accident i'm loving it. And once I have a stable internet connection again I pledge to contribute to documentation, f.i.y im using my cell right now, many thanks to opera, drupal is an excellent cms, cmf, it does what it should, the frustration is part of the journey. We should stop talking about the documentation now and focus on putting it all together. I believe all together there is enough suggestions to make something great, if what I read is right, first a segment for those that are new to drupal, we toss in some tips for those switching from other systems, o.s issues, getting started once its installed, modules you cant do without & instalation, first site, then the more complex stuff, theming e.t.c, besides that the best thing we can do is enforce documentation standards and I believe a lot of us newbie's are in the same boat on that one. One way or another developers need to tell us what goes on, if you think about every device or software comes with a manual some more detailed than others but the manual has to be there, preferably detailed and not in complex developer language. This will also fall on a point made in the discussion about categorising, documented and un-documented module and so on. I am sleep depraved and have been since I started working on this site so I pray i'm not wasting you good peoples time, point blank its time to force the geeks to teach us what they know!
P.s
Oh yeah and verymisunderstood, it never occurred to me that the instalation instructions are in a file called install.txt seems a bit daft now but hec, wulda saved me a lot of grief!
Pdf version
I'm still awake and its a new day, talk about drupal addicted, just a thought there's a module that creates pdf versions of content on site, why hasn't it been utilised for the documentation?
Generally, there is often
Generally, there is often good documentation for many things. But it's usually really hard to find on the drupal.org website.
Things that need better documentation:
Bulk importing of files and images.
Multi-site installation
Installing drupal in a subdirectory
Where to find info on the database structure
How and where to save files and file directories