I hope this post will be read by the people who code and document Drupal.
First, the formalities. I have 25 years experience in programming at various levels.., I am a first-timer with Drupal which I have been evaluating for about two weeks.
First the good news. It's a great CMS. I have evaluated others and it is the best, at least for the kind of projects I need to set up.
Now for some comments, some of which apply to all open source projects. Let's start with Drupal specifics.
For a a cms that is based on nodes, the Drupal site itself does a poor job of structuring as a tree the information needed by people to get started. The current situation is not acceptable for a project of its quality and size. Why couldn't people here access a start node called "Drupal" and navigate down until they find the information that they are looking for? As it stands, the site is a jungle of information that jumps at you from every direction and by the time you are overloaded with it, you haven't found what you needed. Then people start posting questions in forums, often in the wrong areas, and the problem continues.
When I am in charge of a project, no coding takes place towards the next release until the full docs are done. The only coding that goes on relates to urgent bug fixes. All the resources are pooled in getting the docs up to speed so that the end users can understand what the application does. It's no good having something really great like Drupal if it takes you more time finding the docs than writing it from the ground up. Sarcasm aside, I have found it extremely difficult to understand the inner-workings of Drupal and I have years of experience in the underlying technologies (PHP, HTML, CSS and SQL).
This issue is not new and is a real problem with Open-Source. Projects are usually driven by top programmers who prefer to jump in a pool of burning fuel rather than document their stuff. They are excited by the new features and don't realise that building a solid base should be the priority over extending further.
After running 4.7.4 for a while, I am trialing version 5 and at the moment, it is easier for me to enter debug info straight into the PHP code to understand what it does rather than go fishing for documentation.
Surely, it is not that difficult to explain how the data goes from the SQL tables to the web page, passing through various filters and modifiers along the way. Yet, there is no document that I have found here that explains in a concise and straightforward manner how it all happens. There does not seem to be any kind of flow-charting, even basic, to document the internal architecture. That makes it hard for people like myself to jump onboard and contribute.
I don't mean to be harsh on people who are donating their time to produce a very classy CMS. I hope this post can be taken as constructive criticism. If I were not a beginner with Drupal, I would volunteer to participate in writing the docs. At the moment, I am useless and frustrated. I can tell how good Drupal is and yet, milking any kind of customization out of it is like pulling teeth out of a hippo.
By the way, V5 installs like a charm and works well. The problem starts when you need to customize. It's important for for the web itself that we don't have thousands of Drupals looking all the same just like we've had thousands of PhpBBs looking the same. Why isn't there an interface for modifying the look and feel of nodes, comments, pages and blocks. Why do we need to screw around with the php stuff?
Being able to properly customize Drupal is vital to the implementation of most projects and important to the intuitive browsing experience of billions on the Web.
Don't shoot me, I'm not the one playing the piano.
Comments
Starting point:
Starting point: http://drupal.org/handbooks
Developing for Drupal: http://drupal.org/contributors-guide
Drupal's APIs: http://drupal.org/node/326 (which will link you off to http://api.drupal.org)
Hope that helps. As you say, more documentation is always needed. For starters, we need more documentation contributors.
--
The future is Bryght.
...
Access the information they need to get started? You will need to be more specific. Which level of information are you talking about?
Beginner installation no php? we're going to restructure the installation guide soon enough.
Advanced, lots of php want to program? I have hopes for docs from this group http://groups.drupal.org/drupal-dojo
A large gap between the two groups. In the meantime, follow the links Boris provided.
-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
Docs not doing the job
Thanks for the reply. I had no problem installing and running Drupal 4.7.4 and the latest 5 dev which is even easier.
Whenever I have needed advanced information about anything, including theming, it's looked out of date and not terribly relevant to my needs. I've been to all the links given above, they were my starting point. And the more I looked at the docs and the more I felt I was wasting my time. I did searches, looked at a lot of pages overbearing with information and didn't get very far. I need a comprehensive reference that I can look up. I need something that explains to me the various building blocks of the application, what the files exactly do, and what the function inside the scripts do. Whatever has been exposed to the advanced end user to customise needs to be properly documented.
There is no feel to the docs. It's stuff thrown into the mix to plug holes. For example, the theming docs should be clear as to what applies to 4.5, 4.6, 4.7 and/or 5. Some of the files referred to don't even exist. Where is a doc anywhere that explains the basic design philosophy for theming under Drupal? Where is a page that explains the new theme design under Drupal 5? The fact that I am here rather than there shows that there is an issue with the docs.
Documentation is not throwing stuff on web pages, hoping it'll work. Documentation requires careful planning. The needs of all users need to be met, beginners, intermediates and advanced. Whenever somebody browses the docs, he needs a sense of place. Am I looking at V5 docs? Is it advanced or beginners stuff? this site runs under drupal itself and I don't think they have done a very good job of using taxotomy to categorize the docs.
I'll be frank with you, I have no faith in the docs. I found very good bits here and there but I think anyone who is going to make advanced use of Drupal will have to work key things out himself or find the answers on some other site.
I'm looking forward to a time where I will be able to go to docsv5.drupal.org, click on "Advanced" then choose "Drupal Architecture" to get an overview of how it all works. Then I would go back to "Advanced" click on "Theming" and find there what I need, hopefully with a view of the docs that is relevant to my expertise in PHP, SQL, CSS and HTML.
I'm fortunate not to have judged Drupal on what drupal.org has done with it. The organisation of knowledge here is simply dreadful. The site looks good, it is well written but when you look at the way it meets the needs of people like me, it falls short.
Welcome to Drupal docs
Welcome to Drupal docs !!
For a developer oriented person, Drupal documentation is not well organized, but I believe that if you take the time to dig around, and your effort will be well rewarded.
From the kind of question your asking, I think this article http://www-128.ibm.com/developerworks/ibm/osource/implement.html will be a good place for you to start.
It may not have the depth you want, but will give you an idea of the power at your disposal
My take on learning
As a newbie to drupal a few months ago(and admittedly I am still a newb i think), this was how my learning curve went:
1/ Play around with the CMS, be impressed, get a feel for it
2/ Play around somemore :P
3/ Read through the Hooks section of the API docs- this is the fastest way to grasp how drupal works internally (and otherwise) in my opinion
4/ Read through rest of API, the examples, some basic modules included with the core
5/ Build a sample site that includes a few custom modules - even if they are crap or already been done before (you think you can do it, do it instead of downloading the module, compare afterwards)
6/ Build your proper site now
Number 5/6 is where I am now (though I still haven't completely read through a lot of the API). I dont know if this is the best (or even the worst) way to go about doing thing but this was what I did and still doing.
------------------------------
Naruto - narutomonkey.net - Naruto Forums
Good take
This is what I have been doing in the last day or so... digging into the API docs. The Hooks are well explained but there is nothing on the API site that I could find relating to the arguments to the functions. What variables are available globally to the hooks and what information is contained in variables such as $node. I've been assuming it has all the fields from the table for the current node but it's not a good idea to assume before you write code.
My argument has never been that the information wasn't there. It's just not structured well. People are overwhelmed with the amount of information available and have trouble finding a path through it. It took me a much longer time than necessary to find the API site. And now that I am there, it is missing information for me to write my first module.
Note: this reply is
unrelated to the docs or lacks of docs discussion.
But, if you want to start writing modules I suggest you get the devel module. It gives an object structure tab on node pages (maybe others too), and also has a php evaluation form for testing the output of functions using dprint_r() function that will pretty print the contents of arrays and objects etc. It also lets you see all the queries on a page and their timings etc.
--
Anton
New to Drupal? | Forum posting tips | Troubleshooting FAQ
...
Spot on. We need people to write stuff. People aren't showing up to do this. We have maybe 5-10 people on a general basis and maybe another 10-20 on specific cases contributing to the docs. So all the planning in the world won't help a lack of writers.
Short term, rebuild the introduction handbook and clean it out.
Next, rely on the drupal-dojo project to get some intro and mid level developer docs going.
Themeing... not sure yet. Probably a combination of Drupal-dojo and other random contributions at this point. I am spending some personal time on themeing soon so it may be me.
-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
Visual queues
Just a suggestion for the docs. Why not have pages that are visually different from others. For example, a HOWTO page would have some sort of icon or visual cue that could identify it immediately to the user. Same for different levels, why not have something different on the page that indicate that the content is for beginners, intermediate or advanced?
The best advertissement for Drupal is how drupal.org uses it ;)
When I am in charge of a
When you are in charge of a project, you probably also get paid...
Neither our developers nor our documentation writers get paid, so everybody does what he likes best.
Contact me if you want to fund some serious documentation writing, we have qualified people on our documentation team.
--
Drupal services
My Drupal services
--
Drupal services
My Drupal services
A fake argument
To suggest that because you are not paid, you can do things incorrectly is throwing a puff of smoke around the issue to avoid it.
Once you have made the decision to donate your time, you must do things correctly. The way you perform has nothing to do with the decision to volunteer or not.
It's tremendous to have so many good people working on Drupal. If I were not a bunny at it, I would help too. Unfortunately, I am frustrated right now and reduced to post here rather than fix up the docs. I'm not good enough with Drupal to do anything about the docs. However, my experience tells me that they are quite messy, mostly in the presentation and structure, not so much in the way they are written.
You can have the best application in the world, if you cannot communicate with your audience via the docs, you have nothing.
fake argument?
Are you sure you really understand how open source projects work?
I'm sure if you took a poll across the community as to whether killes should spend his valuable finite time doing more documenting instead of developing or debugging, there would be an overwhelming result against it. And the same would apply to all the other developers in his position. As it is they probably wish more people would read the documentation they actually write.
If you took a poll last year as to whether 4.7 should be delayed many more months so the developer docs could catch up, there would also have been a resounding 'no'. Drupal is a fast evolving project that isn't afraid to change the codebase dramatically between releases. That is the culture of the project and most of the developer community is here because of that approach. Sure that makes things harder in other respects like up to date docs or keeping track of things. But I can't see that approach changing.
Even in general terms that is an exaggeration, and in specific terms I don't think you can fairly apply that statement to Drupal. While Drupal docs aren't perfect, they aren't that bad. I'm just a sysadmin with limited development experience but I've learnt heaps from the docs. And after seeing other new developers quickly get involved, the docs aren't useless.
--
Anton
New to Drupal? | Forum posting tips | Troubleshooting FAQ
Open Source must be done properly
If you took a poll across the community, you would find that most think that the docs are not organised properly. Now I am not suggesting that killes should waste his skills documenting. Since this is a team effort, there is a slot for everyone. If it means holding a release for a while longer, so be it.
When you release something that is not documented properly, you encourage a mad scramble in forums or other websites and you lose control over the accuracy of the information. The time you did not invest documenting is wasted a thousand fold by people running around trying to find stuff. People post their own little hack, it works a few times then it breaks.
At the moment, my quest for understanding Drupal is like putting a puzzle together. From time to time, I stumble over a significant piece, usually volunteered by some kind soul who has faced the problem before. Overall, it's two steps forward, one backwards.
I appreciate the work that a lot of some good people have put into Drupal to make it what it is today. As soon as I get off the bunny status and get well-versed into its inner-workings, I will contribute. So far, the extent of my contribution is to raise this matter, post an issue in the documentation area, join the mailing list and step on a few toes ;)
I am doing things correctly,
I am doing things correctly, thanks: I am doing what I like. (and that is to improve Drupal's performance, in case you care). I have no obligation whatsoever towards doing what you like: Me writing end-user docs.
And here's a treat for you: I don't care if people use Drupal. I've never done. Despite this, people seem to enjoy using Drupal and there are many more sites from release to release.
So, after some thinking, my conclusion is: The docs are there, and they aren't all that bad. Maybe the problem is with the reader.
--
Drupal services
My Drupal services
--
Drupal services
My Drupal services
All about perspective
I'm sure the "docs are there, and they aren't all that bad" if you already have the knowledge that the docs are supposed to give you. If you come fresh from the outside world, it is a different story.
Definitely something wrong!
Drappulled, i don't know how you managed to be soooo patient!! it really shows communication (and management) skills in you.
I really can't understand you people at Drupal...with all do respect...really!
Constructive criticisms are blessings and should be considered as opportunities to pause a little and re-evaluate your track....
I could not believe when Killes said that he does not care and he is not a big company ..so on...
sorry, but this shows an attitude...no matter how frustrating the volunteary work is.....
Drupal is not the only open source product .....it may be amongst the best....but what makes people chose one over the other...is the easy way into the product and how to make it up and running in few clicks.....yes few clicks....there are many people (like me) installing open source products on the daily basis just for fun.....
I tried (honestly but not deeply into) more than 200 CMS ...just installing and see from the first shot how fast I can be up and running with some contents.....
Only few CMSs that I could get the "magic" of what I need from the first shot....and Drupal was NOT one of them....Please Don't get me wrong...I do believe that lots of efforts need to be done after installtion any product to get your site up and running...but with the millions of products there.....you just don't want to take the risk of spending too much time on one products and then find out it is not worth it....one way out is see what most people are saying and using....anyway...i think the picture is clear of what i was trying to say...
I got the same frustration with Joomal...but at least there were few places suggested by the joomla org and they were excellent, straight forward and mostly well categorized. Moreover, joomla people published an introductory book (you have to buy) about the way joomla blocks work....and that was the starter i need for kick off....
I am using Joomla for more than 10 sites.....they are all well and everyone is happy....having said that ...I have to admit: I am still not convinced it is to way to go....that is why I am given Drupal more time than the other.....
Finally I have to say this: Drupal is a CMS, for God sake use it to manage Drupal's docs...
Loosen up some more, Killes
You really ought to consider.
Remember the fox and the stork.
And this article http://drupal.org/node/6286.
Soften up an little.
You are one of the old time Drupallers and ought to be getting more mellow and congenial by now. If you were in a big company you would be limiting your chances for transfer into a cushier managerial role with greater stock options, less coding, more golf and foreign junkets. :)
I am not in a big company
I am not in a big company and I don't play golf.
--
Drupal services
My Drupal services
--
Drupal services
My Drupal services
You /can/ help
I think you're misinterpreting things here... The people who develop the actual code are geeks. We suck at explaining things to users, because we don't see just the application, but also the underlying code and how it works. And while I wouldn't like writing documentation either, I'm happy that I don't have to, because whenever I do try to explain things, people usually end up more puzzled than before :).
On the other hand, the part that I do know how to explain, the code, is very well documented. And I pay attention to committed patches to make sure each aspect is documented corectly.
As for how you can help: you've said so yourself. You're a frustrated documentation reader who is perfectly suited to pointing out the problem areas. Trying to set up a global effort for pristine documentation will rarely get you anywhere... the nature of open-source is that it is often in flux and people have to make the best of that. But even if you just help the documentation team with concrete, small suggestions, you'll do a lot. You don't have to write entire book pages.
As for spawning huge discussions, sadly, big proposals tend to generate big discussions that tend to leave people jaded rather than resulting in compromises. My best advice is to make the best of it, and give the community the benefit of the doubt. And if a discussion tires you, stop posting. Good ideas will get done, eventually.
--
If you have a problem, please search before posting a question.
why not a drupal documentation wiki??
Hey drapulled,
I complete agree with you. The organisation of Drupal documentation is extremely poor. The information you need can usually be found, but it often takes a long time to track down and a lot of searching through forum posts, module issues etc. Furthermore, as you say, there is no clear overview of how Drupal works from the ground up so that advanced users can really understand what's going on. Instead you are expected to gain this knowledge through months of experience using the system and modifying/building modules yourself.
But there's no point in us whinging about it, because we are after all the type of people who should be helping to write this documentation.
What I would dearly love to see is a Drupal Documentation Wiki. The main problem I see with the documentation (handbook pages etc) is that it is so poorly organised that it does nothing to encourage contributions. Users cannot usually edit documentation written by others, but instead have to add additional comments or subpages that either expand upon or even contradict the parent node. The main objection is probably that such a wiki would exist "outside" of the whole drupal website structure and drupallers seem to be extremely fanatical about keeping everything connected into the one system (everything's a node). But I think that in this case the 'drupal way' is doing more harm than good.
A documentation wiki, it seems to me, would be ideal for encouraging more contributions. Sometimes I find there are things I would like to add to the documentation but I can't really see much point in adding a comment to the bottom of a list of 100 other comments. It's just so messy!
Anyway, there's my 2 cents! Wikis are dead easy to set up these days, and there's even plenty of free hosted ones (eg wikia.com or wetpaint.com). Has anyone tried doing this before, or anyone interested in trying? Maybe we could set up an 'unofficial' drupal documentation wiki...
Cheers, G
or
You could click the contribute link and see how you too can contribute to Drupal documentation. We are not using a wiki for the handbook when we have our own tools.
-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
i'll disagree with that. the
i'll disagree with that. the nice thing about a wiki is it's easy to get permissions to edit it. right now it's hard to fix bad documentation on d.o unless you're a site admin. there's several pages on the audio module handbook that i'd fix if i could but i don't have permissions and i'm a bit too busy to bother tracking down an admin to delete them for me. if it was easier to fix things the docs would be better.
Exactly. If modifying
Exactly. If modifying existing documentation and creating a bit of structure to the docs was easier then more people would contribute. Adding another subpage just doesn't cut it. It's a common refrain on drupal.org that "if you don't like it, then fix it" but the current documentation setup and structure doesn't really allow the ordinary user to easily fix existing documentation.
Anyway, I think this discussion about poor documentation structure has been had quite a few times before, and nothing has changed. IMO, if anyone really feels passionately about it the best thing is to get together with a few like-minded people and go ahead and set up their own "unofficial" drupal documentation wiki. Action speaks louder than words, as they say...
I was under the impression
that getting editing rights on the handbook wasn't difficult - ie not much more than just a matter of asking: http://drupal.org/contribute/documentation
Maybe that info needs to be made more obvious on the handbook pages themselves? eg something at top of the handbook pages (or in a block etc) stating that " if you want to contribute to the handbook, please read http://drupal.org/contribute/documentation " or something. The existing quick links block might not be obvious enough.
Then again, there are always lots of things it would be nice to point out (eg the troubleshooting faq etc) and if they all got highlighted the pages would be more cluttered and the info would start getting missed all over again.
--
Anton
New to Drupal? | Forum posting tips | Troubleshooting FAQ
Errr...
Andrew, anyone can edit handbook pages...you can just edit them, and they go into moderation. Documentation reviewers review them, then make them live. Send me an email directly. If you're not seeing permissions to do that, I believe that's incorrect...
you missed the change
With the change in moderation with 5.0 coming up we changed that several months ago. We opened it up so anyone can add a handbook page now. Anyone with handbook maintainer role can edit the pages. Barrier is, you have to show enough interest to ask for it. The links that styro gave are as obvious as we could make them be but we no longer have the blink tag available to us to highlight this.
blue tab on tap -> http://drupal.org/contribute
leads to -> http://drupal.org/contribute/documentation
-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
You're wrong here, Boris. I
You're wrong here, Boris. I don't have the permission to edit handbook pages.
When I go to http://drupal.org/node/292/edit for example, I get an "Access denied" page.
I think indeed that this should be changed.
The process to contribute to documentation is currently quite weird. I can either submit comments (which does not exactly help the documentation to get more structured), submit issues (which is quite a slow process and which, again, devolves the work to someone else) or create new pages (which, again, usually doesn't help to get the documentation more structured).
or gosh...
You can join the team. People seem to deliberately be ignoring the clear instructions on existing pages on how to do this and the repeated links to where this information is.
We have several avenues of contributing. Try one.
-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
Wrong answers to Documentation problem
1. if you don't like the documentation you should fix the problem by contributing
Most newbies are not equipped to contribute to the documentation. If they don't get what they need from the documentation, they will abandon Drupal before they are equipped to contribute.
2. It's Open Source. Everyone works for free. Of course the documentation sucks.
Actually the documenation doesn't entirely suck. Nor is there any shortage of folks willing to share their expertise and experience if you factor in folks who contribute unofficially via the forums or by way of external sites they maintain.
The problem with the documentation is duplication, lack of structure, classification, order and discipline. It took me over a week to finally get all the information I needed to decide this week that I really need to roll my own menu solutions. These are problems that can largely be solved technically, which is something the wiki suggestion aims at, and with just a dash of hierarchy and workflow in the submission process.
3. We can't use a wiki or another tool for the documentation. It's Drupal, therefore the documentation solution must be Drupal.
Drupal is not primarily intended as a documentation tool. If there is a better solution for compiling documentation Drupal.org should use it. However, I happen to think that Drupal is a perfectly fine tool for documentation. Unfortunately, it is not immediately evident that Drupal's strengths -- like taxonomy, for instance, and structured data capture -- are being leveraged for this effort.
In the usability world, you never blame the user. It's like a DJ blaming an empty dance floor on folks' bad taste in music.
Contributing
Contributing doesn't just mean writing stuff. It also means testing docs and providing feedback by offering concrete specific suggestions for improvements in the documentation issue queues etc. Or pointing out bits that need clarification or updating etc.
Recent newbies are actually in quite a good position to help write other docs for newbies or provide the best feedback on what the problems are with existing docs for newbies. They don't have the ingrained assumptions and background that more experienced users have. There seem to be plenty of experienced users available on the documentation team to help out newbie writers with technical editing etc.
--
Anton
New to Drupal? | Forum posting tips | Troubleshooting FAQ
I guess it depends on what you mean by newbie
I'm a newbie. Putting aside that I really don't think I know enough to contribute in any way to the documentation effort (short of perhaps making completely unoriginal recommendations as to how it should be captured, tagged and navigated), I also don't have the commitment yet to Drupal that would incline me to volunteer. That commitment is likely to emerge from being convinced of its merits, and that conviction will build more quickly the faster I can learn it and use it.
I'll second that
I am exclusively front-end, don't program at all -- and don't expect that I should have to when using an open-source CMS; CSS + HTML should do all the work for me. This is not the case with Drupal, however -- perhaps it would be if all modules / installs ran seamlessly, but I've been spending a lot of time troubleshooting.
That being said, I always enjoy a challenge to my learning curve, and Drupal has definitely been that. After a lot of experimentation, trial-and-error, and many a drupal forum search, I might actually recommend Drupal to another front-end user such as myself.
Brooklynwebguy, do I know you? I'm a Brooklyn web girl myself.
:: babslafox ::
Drupal Docs are best in Open Source scene
The drupal docs are the best available for an open source project as far as i know. The reason:
1/ the judges of open source CMS award 2006 said that
2/ The API doc blew me away
3/ Maybe the complexity behind the simplicity is difficult to put into a 1-2-3-4 sized description
------------------------------
Naruto - narutomonkey.net - Naruto Forums
Complacency improves nothing
The quality of Drupal docs in relation to other projects is beside the point. Open Source projects are stronger than ever and their communities are very big and growing exponentially. The Drupal community, because of its size and the particular strengths of the Drupal cms, is in a unique position to genuinely exceed the low expectations that have become standard in regard to Open Source documentation.
The difficulty of putting "the complexity behind the simplicity. . .into a 1-2-3-4 sized description" has very little to do with the problems most newbies cite when offering suggestions on shortcomings and improvements.
Yes, well, the gist of this thread
Yes, well, the gist of this thread with all the comment was.....drupal docs are bad or "we've seen better", which I feel is the opposite of the truth (at least in my opinion) no one is getting complacent, in fact drupal docs are going through a nice little revamp at the moment (according to some of sepeck's posts i've been reading), and though far from perfect they are still good and getting better. If more people pitched in then.....(what others are saying).
Another thought though. One of the main drivers of OS is mutual self interest (or so i have read), because people only write modules and stuff, when they need it for themselves, and then they give it away for free, they are really volunteering their time to write a module, just volunteering to give away something they have already done for themselves. But there is no scenario where a person directly benefits like this by writing docs - they already know it so gain nothing by writing it (maybe distantly benifit though, but not like writing a module). Its for this reason that there are far more people willing to volunteer modules than docs.
I think i somehow contridicted myself here somewhere but nevermind.
------------------------------
Naruto - narutomonkey.net - Naruto Forums
Certainly not, for CMSs yes, not FOSS projects in general
Take a look here http://www.postgresql.org/docs/.
It is all clearly laid out and easy to read. It must be said that the technical proficiency of the contributors and users in their domain is much higher than with a CMS like Drupal.
A CMS has different aspects to it, database, html, themeing, programming and a whole lot of other things which have to be combined and it is unlikely be that simple. But you can see how properly outlined their documentation structure is. There is also a part where contributors links refer to off site pages, all clearly laid out.
What my proposal below describes is for a proper document outline to be created that both official and unofficial documentors can fill out.
There is also the issue of styling
Let us consider the style the official Drupal.org theme as an example. There are bold menus on both sides of the page to issues which for most of the time are not relevant to the reader's immediate interest and yet they attract attention by their very nature.
Without any formal or casual knowledge about design issues, even I myself know this is a no no.
At the very least the fonts should be normal rather then bold, and the user should have the option of hiding or minimising blocks they don't need.
The issue for me is more about organisation, style, layout and accessibilty of the content, rather than quantity and quality, which is quite good for anyone who is diligent and willling enough.
The real issue is having to spend 6 hrs looking for searching for info and waiting for responses on an issue that takes 20 minutes to implement when all the necessary info is located.
The time ratio definitely goes down as one becomes more familiar, but it is quite frustrating at the start.
A Revolutionary proposal for creating documentation
One thing we all have to accept Drupal leaders included, is they don't really have the time to do everything right themselves because they are mostly volunteers. No one is being paid to do everything right, and do it to completion. In any case people are bound to make career moves even when they work on a paid basis.
Major Drupal contributors also have their own Drupal related business or other Web/IT work to attend to.
Lets face it, the IBM guys are people who are paid to do what they do. They were 3 guys working on it, and over 6 month period and what the produced is barely a tenth of the size of a proper guide, yet it is the best example of an introduction to Drupal I have seen so far.
We don't know if they were on it full time, or had other assistance, but at 3 x 60K a year for 6 months that is 90K, and they probably earn a lot more but I don't want to flatter them too much :) and dishearten other Drupal contributors to boot :). Drupal volunteers can't compete with that, unless we are really dedicated and well organised - we shouldn't kid ourselves.
The right approach here is not for everything to be created at drupal.org, but for Drupal documentors to create a document outline, with chapters, topics, and desired content specified. Even this part of the process can involve the community
Instead of real content there will be links to contributors websites, probably wikis, where their versions of the topics will be created. Readers can then vote on which ones are the best and Drupal documentors can select which of them will go into the Official Handbook, which may not necessarily be those with the top votes.
Drupal documentors can also create their versions, but in their own sandbox, which are also linked to just like the others. It could even be the case that some of the unofficial guides may be so much better than one what Official guys are producing that they may even decide to apply their efforts to those instead into the final Official version.
After some time each chapter or topic will be well fleshed out and the best ones can make it into the Official Handbook. If the manual can also be developed around a real or imaginary project, using a real website, such as the new.drupal.org, that will also help.
The approach here is for progress to be through small but well focused contributions, in well defined areas. Having thousands of cooks will spoil the banquet, it the cooks are divided into small teams with well defined tasks in preparing the banquet, you will end up with great banquet.
One thing that we have to realise that Drupal is a moving target and new versions may come about before the manual is completed. But so long as the Drupal version involved one provides a strong enough foundation for developers to work on, once they create a project with that version they might even stick with it for good where that project is concerned. Module breakage and all that.
In any case the links can point to the appropriate versions for newer an older versions.
My message here to Drupal leaders is: create the structure, setup some guidelines, provide some advice and control, and the community will do the rest.
Just as with modules, business can sponsor some pages by providing staff or paying bounties to support their creation, and have their shiny logos shining out brightly from the pages if they want.
Now, does anyone have a interesting project which can set the framework for an interesting manual?
The only way to ensure that there is good documentation...
...is to step up and write/improve it yourself. If you're not doing that, then you have no right to criticize, imo. Especially given your experience level.
If you had to use a debugger to figure out something you didn't see documented anywhere, then DOCUMENT it!
Every time I figure out something new or answer a question, I write a page about it. And after awhile, they start to add up. They help other people, and other people contribute and make them better. As a nice aside, it really helps me to understand Drupal better, too.
THAT is how documentation improves: by action, not by wishes.
Why the sensitivity??
Drapulled was simply doing exactly what you stated: he's trying to contribute in the only way he can. He doesn't know enough to write good documentation about Drupal, but he sure knows enough about documenting to supply some constructive feedback about the current state of Drupal documentation.
And yet I find so many Drupal developers that seem to react to constructive criticism as simply criticism. There's plenty of great documentation about Drupal here if you search for it, the problem is the lack of organization.
Drupal developers manage to get together and forge a design plan for new versions of Drupal, why not do the same for documentation? I think part of the frustration of developers here is the overwhelming burden of clueless and semi-clueless newbies. (me being one too) The only way to reduce that burden is for experienced developers to give those newbies tools to become less newbie. Then they can start to contribute and hence relieve some of the burden on others.
I've been struggling with Drupal now for several months and I'm just starting to feel comfortable. I recently wrote a post on handling Teasers in CCK and I'm proud of that contribution, but it took way too long for me to become competent enough to contribute.
What Drupal needs is an infusion of new, knowledgeable contributors, and that will only happen when core developers take enough time away from development to clean up the docs.
Here's a suggestion
Why not set up a Drupal wiki immediately and dump a ton of the existing documentation there. Make editing of the wiki available to everyone. Encourage newbies to add "stubs" where additional information is desired. (because newbies can't provide the answers, but they know the questions) Newbies will be able to build a structure for the documentation, but they'll need more experienced users to fill in the blanks.
The easier it is to edit the material and move it around, the quicker something useful will evolve. Let everyone in the Drupal community bang on this documentation for a few months, and then copy the best edited material back to Drupal.org's handbook.
In other words, use the wiki as a draft copy, without the danger of damaging the current stock of material.
I'll help out with docwriting
If you do that, I'll spend time each day writing stuff for it. I can write a super clean and concise description for just about anything. I understand how PHP thinks. I DO NOT understand how Drupal thinks. If I could get some faster, better, or even some help in the forums when I post a question, I'll take that info and work it into a documentation system. That would be so easy for me. I could do my part in helping this project grow stronger.
--
Joel Farris
"...and that's the way it oughtta be!"
****
Joel "Senpai" Farris | certified to rock score
I have gone ahead and
I have gone ahead and requested an account to be created on wikia for drupaldocs. They will let me know in 12 days time if the request was approved or not. If approved the community can then takeover.
In the mean time a mini wiki has been created at http://scratchpad.wikia.com/wiki/Drupaldocs
People are welcome to contribute there. The only problem seems to be the advertisements on the site. I have no idea how to get rid of them.
Oh and by the way just to preempt the notion that I want to make money or anything through it - Once the wikia is created I will gladly transfer the info to drupal.org and the admins can then take over if they want
Regards
--
Thank you manuj. I have bookmarked this wiki.
There's already excellent doc off-site and it's by IBM and Lullabot. I don't consider it heresy.
Caroline
Why?
Why would you not want to join the docs team and request access here? It is well documented in several places how to do this. It's sad that you and others don't actually wish to actually participate in the established process that already exists right here on drupal.org.
The IBM docs are not likely to be updated per the interview with that team. Lullabot has articles that their members write as do several other sites but a lot of this information does make it back into the handbooks and they are not necessarily complete information that others can edit as they are not here.
-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
He, I guess he had to do it
He, I guess he had to do it cause he could. Children today...
--
Drupal services
My Drupal services
--
Drupal services
My Drupal services
I have gone ahead and
Great. I've copied the drupal handbooks parent page across as a starting point. Obviously it's not much use just having a copy of the existing Drupal docs, but it's an ok way to put up some structure to begin with.
At least this way *everybody* can easily contribute without having to sign up with the documentation team. If it works well then new information which is added to the wiki can be transferred on the official drupal.org handbook pages.
...
any registered user can easily contribute to the documentation.
Create content > book page or go to content, click add a child page.
Not sure why people are persisting in posting otherwise.
-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
any registered user can
Sorry, didn't mean to imply that they couldn't. My point was that they can't edit existing documentation.
Building good documentation is just as much about *editing* as it is about *adding*. At the moment your average registered user can only add subpages or comments.
It seems to me that not many are keen on adding entire subpages because they feel they need to write something significant. Whereas with a wiki, you can just make a stub and everyone else can help finish it off. And comments... well, they are comments, not documentation. Wikis have discussion pages for exactly this reason. It saves people from having to read through a hundred comments (often contradicting each other) to get the answer they need.
...
Then please feel free to join the docs team and request access. We're not a bunch of ogres despite the characterizations by some. I'd love to see people offer to help existing efforts rather then fork efforts. We have an issue queue here on drupal.org, we can edit handbook pages easily enough and even have a fairly low volumen email distribution list.
-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
Hi manuj, I have been to the
Hi manuj,
I have been to the wiki site and have a few points to make.
I think in accord with my previous posts what is really needed is a book outline with links to articles relating to the topics, which can then form the basis of an unofficial manual, through peer review.
If chapters or sub chapters are created at the wiki, they should be in another part of the wiki which contains a duplicate of the book but with topics fleshed out.
There is a lot of good documentation already at drupal.org, and a lot of the links should point back there. There are also good unofficial documents with whose links that can be placed there. If enough of them are read and people get to like them, they can be nominated for inclusion into the Drupal Handbook where their topics are lacking and permission can be sought from their authors to be added, or links can be make in Drupal docs pointing to them.
If you check http://www.postgresql.org/docs/techdocs.2 you will see an instance of what I am speaking of in the case of unofficial docs. When you think of it, the IBM articles for instance can go into separate sections within this outline, in both an unofficial docs section, as well as in the appropriate places the handbook outline.
I noticed one thing about the wiki, I don't know about the links importing process, but if the Wiki is named Drupaldocs then all the URLs to the pages should be prefixed with Drupaldocs. Does that depend on approval?
I have already made an entry pointing back to the History, mission and community section at Drupal. I don't think the whole Drupal outline is needed
I also agree with you that
I also agree with you that for the documentation to make sense it would have to be done in a book outline.
With regards to chapters and sub chapters I guess that is for the community to decide as to how they want it.
I also agree that there is a lot of good documentation at drupal.org and the links must point back to those articles.
One point that everyone must remember here and it is of UTMOST IMPORTANCE -
The Drupal handbook pages are © copyright 2000-2007 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0
So when moving stuff to the wiki pages people need to make sure they are not violating any copyright laws.
Regarding prefixing Drupaldocs, I dont believe it depends on approval.
Just saw your entries on the wiki pages. Thanks for the start.
Regards
The reality
To suggest that somebody who has been playing with Drupal for a week or two should contribute to the documentation is like saying that the delivery boy should run the mainframe. He will just pass on his confusion to others and make the already confused even more confused.
If I felt up to it, I would have done so. Instead, I have taken a different route to improving the docs and started this discussion as well as joining the mailing list. I believe I am of better use here than writing about stuff I don't understand.
On the contrary...
This is the very best time to help with documentation efforts. If you wait too long and start to "get" Drupal, you can no longer be as useful because you don't remember what documentation was missing for you when you started.
I wrote my first docs for Drupal when I was about 2 days in. I still had A LOT to learn. I had no idea what hooks, etc. were. But, I had to figure out how to make a local copy of api.drupal.org. So I read the API module code, fiddled around, documented all the steps I took, and threw these into a handbook page. I left notes in the page where I couldn't finish/didn't understand something. A couple people came by later and left comments that said things to the effect of, "Well you actually don't need to do X, try Y instead," and "Such and such worked for me, try that." These later get incorporated into the text, and everything is happy (although I should probably revisit it now that the 5.x version of the module is out).
THAT is what's frustrating to me and other people who actually do write documentation: when people who haven't contributed anything to it start throwing out barbs. "Constructive criticism" to me is something actionable: for example, placing a bug report about a page that says, "I tried following these instructions, but when I did X, it didn't work." Someone can take that feedback and fix the text, which benefits everyone. Similarly, "I found page X on such and such topic under Y section. It would've made more sense to me had it been under Z section instead." This is something actionable; we can discuss whether or not it should be moved, and then move it if appropriate. Same with proposing an alternate outline for the developer documentation, for example. But vague statements like "it takes you more time finding the docs than writing it from the ground up" help absolutely no one and just make the people who are pouring hours into improving documentation (all like 10 of us :P) feel like, "why bother?"
It sounds like one of your pieces of criticism is, "I don't see any flowcharts that explain the page lifecycle." This is something you could do, right now, both to help enhance your understanding of Drupal and help other users. Pull out your debugger and document what you see. It might not be 100% right, and that's ok. Post it to the documentation issue queue and ask for feedback. Because it's much easier to correct documentation than to write it, I have a feeling developers who normally are too busy coding to worry about docs would jump at the chance to help you refine it so that it's a usable document for the entire community.
Hopefully this addresses zoonunit as well.
I agree in principle
While I appreciate your intentions, I don't think it's reasonable to expect many newbies to whip out a debugger and contribute after two days of looking at Drupal. Some of us don't have your skills. :-)
And the real problem with Drupal documentation is not the quantity. There's PLENTY of that. It's the quality and organization. This is where the handbook falls down on the job. The best way for a newbie to learn something is to read a highly structured, sequential story that builds knowledge in logical fashion. Not by reading thousands of snippets of information scattered through a million posts and accessed through searches. (how does a newbie know what to search for?) The best way to BUILD such a document is to make the current content easy to reorganize, condense, and update.
A wiki is much better at allowing the reorganization of content and the cutting and pasting needed to aggregate all the content, vs. the book module, which is better suited to moderated content and lots of contribution via comments. All that material needs to be crunched down at some point.
We have a chicken and egg problem here. The coders are already busy coding and writing docs, and they'll be even busier moderating and improving all those horrid newbie stabs at documentation, and the overall quality will still not go up until the documentation is reorganized.
If you want an army of people to help tackle a problem, it's wise to make it as easy as possible for that army to contribute. And us newbies are eager to do so. We're just wandering around in the dark trying to find the best way to do that. That means challenging the status quo and thinking outside the box. (pardon me for the use of that horrid cliche, but it fits)
One thing I'd LOVE to see, is a breakdown of the arrays and variables exposed by Drupal to the user. This is the first step toward building some new code. (I've found ONE example of this from an old 4.6 post) We need explanations on how Drupal themes and formats the node content; how data is split and stored in the database; how comments differ from nodes. Heck, what is a node? Most newbies are clueless. All this stuff requires a background in Drupal core to explain, but it also requires a person good at exposing this to the unwashed masses.
A tall order. That's why I think a wiki might be worth trying. Anything to grease the wheels.
Let me give you an example of what I mean
I just spent over a week ferreting out a solution to Teasers in CCK nodes. I did this by searching through literally hundreds of posts, sending emails to several module developers, and reading sparse documentation on three different modules. I also spent a bunch of time analyzing the API and the Drupal database tables to understand how Teasers are handled. This took far longer than it should have, because I was wandering in the dark.
Once I achieved a solution, I shared it with the community here: http://drupal.org/node/106766
The original post is a bit sparse. (I wrote it at 3 am) I'd like to go back and flesh it out a bit more, but I can't even edit my own posts. I even posed another question and was helped by cwells to find an even better solution.
Now, what's needed is to aggregate this solution and post it somewhere in the documentation. How to do that? It's not very clear.
And if the solution is correct and basically approved by knowledgeable coders, (we want to make sure solutions are secure) then all the preceding posts that led up to this solution should either be eliminated, or pushed down in the search priority. Better yet, the handbook needs its own search.
Otherwise, the next person who wants to use Teasers in CCK will have to wade through all the same posts that I did to lead up to this solution. (hopefully they will stumble on my post first) Not a very productive way to learn and share knowledge.
And not a very rewarding experience for this newbie struggling to contribute back to the community. Now, imagine a wiki (or improved handbook) that allows all this material to be reorganized and aggregated. An improved handbook seems like a worthwhile goal for the core developers.
I would recommend...
In terms of what to do with your post, I would recommend "outlining" your post as a sub-page of the CCK handbook, probably at CCK for Themers. This guide is referenced in the CCK readme, and is a logical first step where people using CCK would look for help. If you don't have access to this tab, post to the documentation mailing list that you want to join the docs team, and we'll hook you up.
DONE
Per your suggestion, I have put my toe into the documentation waters and it's very chilly there. :-)
See: http://drupal.org/node/106951
I might suggest that if you want more contributions from newbies, display the link for adding documentation more prominently on the Handbook page. It's lost down at the bottom.
I might also point out that a lot of people have been making lots of very specific suggestions for improving documentation. It isn't all "vague." What we need is a very easy way to register these suggestions as an issue. I seem to remember that there is a way to do that, but it isn't easy to find and doesn't even make the front page of the handbook!
And take a look at this page about commenting on Handbook pages. Does this sound very inviting to you? The message here seems to be, "don't mess with documentation unless you know what you're doing."
Make it easier to contribute suggestions, and newbies will respond.
sigh
How can it not be easier to contribute than anyone with a registered drupal.org user account can add and edit the pages they contribute? You certainly were able to.
-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
Yes, but...
I've dedicated about 3 months trying to learn enough about Drupal to contribute. I'm only now starting to stumble across solutions and I'm still clueless about what goes on inside of Drupal.
I guess that's one reason I get frustrated when someone suggests that newbies should be writing documentation and how easy everything is. The problem was not learning how to post documentation, it was the three months of stumbling around before I knew enough to POST documentation.
The biggest improvement I can imagine for Drupal documentation would be a beginner's guide that explains the concepts of nodes, taxonomy, etc. Then explains in serial fashion how data is processed and formatted inside Drupal core. Oh yeah, and how about a chart that shows all the Drupal variables and arrays that are exposed to the user!
If the veterans who know enough to write documentation need suggestions from newbies to improve the existing docs, than I suggest the admins make the issues process so clear and obvious that newbies really begin to file these issues. Maybe a PR campaign. :-)
Have you guys considered a weekly chat room meeting where newbies and veterans can trade questions and answers? Maybe that will be one way to train a larger army of contributors.
BTW, I have high hopes for the Dojo....
...
I know I answered you directly on more then one occasion in the forums on the process. I in fact took a vacation from Drupal for a brief while specifically because of people refusing to read links provided.
I get frustrated when people refuse to follow the multiple provided links and continue with random commentary that demonstrates they haven't even followed the existing stuff that is written.
-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
I always like to use the Youtube vs. Google video example
Why did Youtube succeed against the much bigger and more powerful Google video? Most analysts agree it was because Youtube simply made the video process EASIER than Google. Small improvements in usability can make huge differences on the web, where people calculate their time in nanoseconds.
If you see lots of people being confused and bringing up the same issues time and again, ignoring links as you say, that seem obvious to you, maybe that's a signal that some improvements could be made. Perhaps it's not obvious to them. Group intelligence (or lack thereof) can be a powerful indicator.
Steven, I write books for a living and have 250,000 copies in print. If people aren't buying my books or are giving me bad ratings on Amazon, I can't just say it's their fault for not appreciating all my hard work. I've got to take their input to heart and figure out how to do a better job.
I think we're all just trying to find ways to make things better. That means throwing out a lot of ideas, some more appreciated than others. :-)
Best wishes.
edit:
incorrect placement.
handbook page ownership
FYI, as part of a "bug" fix to the book module, whoever edits a book page now becomes the page's author. This may make the situation more complicated, since if someone on the doc team edits a page, the original author will no longer be able to edit it (AFAIK). See: http://drupal.org/node/93678
---
Work: BioRAFT
Great! :D
Now some counter-suggestions. ;) Not really; just to show you how this works:
Good suggestion! This is a suggestion on the documentation tools.
The handbook is generated from the core "book" module. So the first place to go with this is to submit an issue to the Drupal project, choosing "book.module" as the component. Mark the version "5.x-dev" (so it will go into the newest version of Drupal), and make it a "normal" "bug report."
The title of the issue might be something like: "Usability: put 'add child page' links at the top of the page as well as the bottom" (that might be too long, but you get the idea).
Your description could be something like:
"I've been working with Drupal for X months and didn't realize that I could add pages to the handbook, because the links to do so were buried at the bottom of each handbook page. It would've been clearer to me had they also been at the top of the page as well."
Now, if you want to get really fancy, you could even try your hand at creating a patch for this change. If accepted, it could be your very first core code contribution. :D But either way, this gives the developers something concrete to act on in order to improve the usability of Drupal, in the place that they will actually go to look for such things (as opposed to buried somewhere amidst a big flame war on the forums), so it's very much constructive criticism.
Now here, you've identified a problem with the content of a page. So the way to address this is to submit a documentation issue, the same as you did for your Drupal issue. Identify the text you found unhelpful, and suggest alternatives... either as a few sentence corrections, or even a whole re-write of the page. Again, YOU are in a perfect position to do this, because you are looking at this page from the eyes of a new documentation contrubutor; the rest of us "old fogies" look at that page and don't see a problem -- so give us info on how to fix it!
And finally, thanks very much for being one of the few who has put their money where their mouth is, so to speak. And welcome to the world of documentation. :D
That's a wonderful description
Now, why don't we put a link explaining the issues process at the top of the handbook page, so Newbies can find it easily and be encouraged to contribute? That way, you and Steven won't have to explain this over and over again every time one of these discussion threads comes up.
I guess that's the real point here. I know you guys work very hard, and there are better things for you to do than to "train" all us newbies through discussion threads. That's why effective documentation is so valuable. Even documentation on documentation....
Teach a guy to fish...
Btw, we DO appreciate all the work you guys do. It's just frustrating for some of us that it takes so long to become Drupal veterans. I've spent 3 months slogging my way through Drupal and I'm only beginning to become productive enough to contribute.
P. S. I'll file an issue on this point. :-)
Probably because...
Probably because:
a) Most people just complain about the documentation, rather than offer to do something about it, so I've never found myself in need of typing up those instructions before. ;)
b) We don't know where would be a logical place to put such documentation, because we're not new documentation contributors (hint, hint ;))
Looking forward to your issues. :)
I posted this as an issue
My first one. There will be many more as a new documentation specialist.
Be careful what you wish for...... :-)
links placement?
Hi Webchick,
I thought the links placement is just decided at the theme level in the page template? Maybe the bluebeach theme could have a node-book.tpl.php with an extra set of links at the top?
---
Work: BioRAFT
Clarification...
The debugger comment was directed specifically at the OP, who said they were using a debugger instead of improving documentation. It irked me, because people with that skill set and who are new to Drupal are the only people who can help improve the developer docs.
But the general statement also holds for newbies in creating documentation that's useful to them. An issue on the issue queue stating "I finally just wrapped my head around X topic. This is what really would've helped me grasp this faster: [insert outline, or links to another piece of documentation from another project as an example, or a few of the pages that need to be consolidated, or whatever actionable plan of attack]. Even better: get a bunch of people at the same skill level together and plan out what would need to go in "the ultimate Drupal newbie tutorial" and make it happen! That's what the folks in the Drupal dojo group are setting out to do.
I don't really care what interim tools are used by people (wikis, etc.), as long as the end result ends up in the handbook. Derek and I used Google Docs to get our thoughts in order while we were re-writing the CVS handbook. If a wiki works for you, then great. I just don't want to see 1500 "unofficial" docs sites who are re-inventing the wheel rather than improving what we have here, which is the only resource that 90%+ people are ever going to see. If the tools need improving (which they do), then again, please create actionable feature requests on the book module, with things like annotated screenshots, a clear and concise description of functionality, and/or links to demos of other apps that do what you mean. With a plan of attack, developers can improve the tools. But they can't with vague statements and criticisms.
--
Webchick, drapulled was using the debugger to figure out how Drupal works because he could not figure it out from reading the Drupal doc alone.
Exactly.
And because they didn't document their efforts (or, failing that, even specify what tripped them up in the first place), the next person who comes along is going to have to do the same thing. And the next one... and the next one... until someone finally steps up and documents it, which might be months or years from now (since those of us who already understand how it works don't know what new users are being tripped up on, and vague posts like this certainly don't help). And in the meantime we'll only see more of these "constructive criticism" posts. Ugh.
So yes, "imo" (in my opinion) what earns you the right to criticize (or, if you want to get technical, "what will allow your criticism to be constructively acted on") is active participation in making the situation better. And I will bend over backwards to help anyone who wants to chip in and start doing this, as will anyone else on the docs team.
I agree
Not only do I agree with Webchick that newbies SHOULD be helping write documentation - especially for other newbies - but I have DONE SO. With six weeks and 3 sites under my belt, I wrote a book for newbies. It is in the Handbooks section under Installation and Configuration.
I think Intermediates should also be writing docs for other intermediates.
Now, there is one point that seems to have been lost since the post that started all this, and it is something that I think is critical (Yes, I too am a professional project manager): When a new release of any product is being planned, there should be a considerable amount of effort put into the planning - including the documentation. Some people even think more time should be spent on planning than coding. I may not go that far. But certainly, one key piece is what goes into and out of a major piece of code, along with how it's formatted.
Going back and documenting after the fact is always going to be problematic. One of the main reasons for this is by that time you know what it does rather than having planned it out in advance.
Nancy W.
now running 4 sites on Drupal so far
NancyDru
Listen
Clearly, someone who is not listening.
... and wouldn't it be just great (and perhaps a novel idea, dare I say...) if contributors of code just did that in the first place, and not left it to people like you/us, to do - We might just get more stuff done quickly all round, donchya think!
And it can, and does get done, albeit by the more professionally-minded (including yourself Webchick - I'm not just having a go at you) - Greenash's work, is a model for all. When he releases, he delivers the FULL package (His after-support sucks mind, but his delivery is faultless! ;) )
Ya know; I just couldn't release anything, in my name, that wasn't a best-effort attempt... whether that be a bug report, bug-fix, or module - I've said it before; it's no coincidence that the household name software we all know and use, is that, because of documentation... well structured, clear and accomodating.
To all 1st-time users, my advice to you is this: There are basically 2 types of Drupal users; the lucky, and the technically curious...
If you're lucky, Drupal works first-time and provides everything you wish to do, out of the box, no bugs.
If you're technically curious, be prepared to put in the time to craft the beast but remember, your time is NOT free.
Mike
------------------------------------------------------------------------------------------
A simple thanks to those that help, a price worth payng for future wealth.
No, you listen
Yes, greenash releases full documentation. Not on drupal.org. On his own site. If his own site goes down or goes away then all of that information is lost to the community. If someone stops working on Drupal for some reason (like a one year vacation), then you'd better hope someone has a local archive and that his stuff is under a friendly license, if it's not, again poof.
As to His after-support suck, well, gosh, I'm sure that after spending all that time writing and releasing software for people to use, it makes him feel warm and fuzzy to find people in the forums saying he sucks. I'm sure that yours and similar attitudes will continue to make him and others want to contribute free software to people. Consistent and thoughtlessly mean comments like that drive a reputation in a community. It generates memories and positive and negative memories of people can often determine the type of help they receive in a community.
This site relies on content contributed by people you don't pay. By people contributing their code, support and knowledge on a best effort basis. Constantly attacking those contributor with snide little comments merely serves to drive people away and make them wonder if it's worth helping people with that type of attitude.
-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
Yes, greenash releases full
As is also the case with much other useful information that resides on the website's of other users.
Memories of Drupal being "bailed-out" with free donated servers?
Maybe I should start using bold more... so that you can see my smilies easier ;)
His after-support does suck, but the fact he delivers a full package, at least (in principle) gives someone else within the community a fighting chance of using, and supporting it... that is the raison d'etre of open source isn't it?!
Here we go again... the use of the "free" argument to try and shame those that question, into submission. If the fact that people don't "pay", is your strongest argument, then consider the thousands upon thousands of man-hours worth of "free" feedback, bug reports, suggestions, "snide remarks", and Drupal marketing contributed by Drupal users (including threads like this) - Without which, Drupal would not be where it's at today, including the various Drupal shops and other economies that has sprung-up around it.
Drupal is not free.
As opposed to your more "upfront" way of doing it I suppose?
I really don't get people that argue for releasing incomplete, inferior product.
Mike
------------------------------------------------------------------------------------------
A simple thanks to those that help, a price worth payng for future wealth.
...
Not relevant and an inaccurate retelling of events, we weren't bailed out, people whom you do not pay had been providing server, bandwidth and coding for years before that. I know because I was involved in writing that request for help, what the funding was spent on and donated cash. Nice try.
No. You damn with faint praise so often and consistently I remember you specifically. Using smiley's when you do so is a way to claim you didn't mean the harm your words caused. In general I ignore you because I know you hold our efforts and the efforts of those who contribute to our documentation in contempt. You seem to delight in tearing down and yet refuse to help build. Your words harm those who do contribute and hold back and make hesitate others who might.
I didn't say free. I said;
Nothing about free there, everything about the hard work people you do not know trying in their spare time to help.
You said we release an inferior product. Yet you refuse to help. I am used to and know you will not help, but you snipe, you mock and you tear down the efforts of people who do. You actively harm members in our community by doing this. It is not nice and it does not help.
I repeat
As a last bit to try and help you, your signature line has a spelling error. This is not a slam, I really want you to seriously consider your own signature line and the effect your words have often had on those people who try to contribute to this little inferior project that you seem to benefit from.
-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
Oh Dear!
You either have too much time on your hands or just love to debate; either way, much of what you wrote above either completely lost me, (largely due to being twisted totally out-of-context), or was, quite frankly, a load of BLOCKS.
If you want to get all pedantic on the use of such phrases as, "contributed by people you don't pay", and its implicit meaning of free, well... we should share a beer one day as I love language games, but I ain't got time for them here (I am left wondering though; if you didn't mean to push the point of "free", why on earth even use the phrase?!).
Anyway, you're starting to get personal now and I really don't give a toss what you think (you'll prolly twist it anyway!) - I'm not here trying to prove anything, but if you are... do your research before making claims about people (in writing) - You might then discover precisely how much BLOCKS you wrote in (your) paragraphs: 2 and 5.
PS... thanks for the typo-note ;)
Mike
------------------------------------------------------------------------------------------
A simple thanks to those that help, a price worth paying for future wealth.
deleted
deleted
i've got no sympathy
i've got no sympathy for people complaining about the docs. let them go look at mambo's non-existant docs and they'll come back begging for ours. the excellent docs were the reason i picked drupal as a CMS. and once i got started i cut my teeth fixing docs that hadn't been updated to 4.7 from 4.6. because the best time to write docs is when you don't know how something works. you know exactly the questions a noob would have and answer them.
is to step up and
Wrong, webchick. Everyone has the right to criticize. You have the right to disagree with any constructive criticism and solution that comes your way, however. You have the right to feel that is unfair... You have the right to have emotions and feelings. But in my opinion you should not tell people what they should or should not do.
Caroline
Go wiki
I think that if there was an official wiki documentation, contributions would skyrocket. There is just a whole mid-set to it that would be more encouraging to newcomers to contribute. Wouldn't the liquid wiki module do? no need for using mediawiki or anything like that.
------------------------------
Naruto - Naruto Forums
Drupal attracting a lot of adv developers who find docs lacking
I am beginning to think that Drupal is now attracting a lot of skilled developers who expect or are accustomed to better tools, documentation and online help. In their non Drupal activities probably find answers through a small pool of developers and advanced users who can quickly get to the nub of an issue.
Drupal is different in that it is a pyramid with a very broad base of newbies and non techies whose forum posts developers skilled in other areas have to wade through to get to find the right answers, and I think the approach of core developers and documentors needs to adjust to this. The noise level in the forums can be so high
Perhaps a separate mailing list for those approaching Drupal in a more application oriented and a less websitey basis, although both parts can often overlap. Even then many developers approach websites as simply another application to develop, with the web part not meaning much besides a different set of considerations.
One Drupal application which illustrates is http://astbill.com/whatis which is Voip administration application built on a Drupal base. You will see that it is the kind of app that a person approaching Drupal with intent to do something like that would walk into a wall.
This article sheds some light on what some developers think of Drupal, and what some people might be considering Drupal for.
Question...regarding use of Drupal
I believe i understand the
I believe i understand the ideology of asking new comers to help document. It would seem to me that there is noone better to explainsimply A new comer would tend to explain it in a way that is easy to absorb by another new comer. (Birds of a feather, "Doc" together).
With as much energy that was used in this thread to point out the downfall of the docs, that same energy applied to the docs themselves would have proved more fruitful. Obviously the Doc Team needs some help with documentation. Drupal can be bent and twisted in so many ways, I would have to venture a guess that in many areas, it would be difficult to come up with a every size fits all doc that suits every possible possibility with Drupal. That in and of itself, poses some situations too.
That aside though, I would like to take note that I've seen quite a few new individuls stepping up to the plate within the community. I applaud all enthusiasm toward the project.
Back to the original request way up there
Back to the constructive criticism expressed in the first post :
I don't think a newbie can offer this kind of doc. Providing explanations on how Drupal works, from index.php, BOOTSTRAP to the include files and the modules, the hooks, the contributed modules, the themeing functions...
a concise yet all-incompassing explanation, through diagrams, pictures, clear wording, done by someone who has a very good grasp of ALL of Drupal, not just the 3-4 things he's specialized in... the big picture, from a developer point of view. I wanted this so badly myself and never found it. So I still don't know. I have struggled so much to figure it out on my own, me an engineer with 15 years of experience in programming and software project management, I waded through the documentation, and pulled may hair out. The forums are so much more useful. I must say that Douglass book (which I ordered from an online store) helped me with themeing, not enough to be able to create a theme, but to mess around with some stuff on the page, although as I was reading more and more of the book I realized how outdated it was... as far as contributed modules, and it lacked a comprehensive reference-like part about themeing, which it covered quite superficially. It did however explain the basic themeing architecture 10 times better than the theming doc we have here.
What's also lacking in the online doc is the hability to insert images through the doc : screen shots, diagrams, etc. Something that can be done with other tools. I am sure that this can be implemented though.
Caroline
scratch my back...
Drupal friends, I would be delighted to help with documentation editing / writing / usability testing....especially if you can help me solve my pending (and desperately urgent) problem, which seems unanswered in any of the current forums or pending issues.
I've done documentation / help desk copywriting before, and as I'm going to need to create user manuals for the site I'm creating anyways, I might as well lend a hand with the documentation here too.
Especially if you can help me, prettiest of pleases.
:: babslafox ::
My impressions
I think Drupal handbook needs improvement in content, as well as in usability. Therefore I completely agree with the first post and with some more comments arguing for improvements.
However, I fully understand the intention of Drupal core staff not to use wiki or other external tools for a core durpal function. The Drupal community should be able to solve this issue itself. Improvements on handbook can be achived by improving the functionality of the book modul or by new contributed modul for handbooks.
Functions should allow newbies and contributors with non native english, to provide even minor changes, add-ons and corrections to existing stuff. Mechanism for fast reviews and publications should be also realised. I guess, these are other use-cases than just commenting existing book pages. If all these features do exist in present handbook mechanisms, then please educate all newbies much better how to use them.
Doka
Doka
Proper software documentation
The current documentation leaves a lot to be desired. Rather than documenting software usage, the majority of it seems to document the underlying code. As a prospective user of Drupal, I could care less about how the underlying code works. I want to know how to get the software, as written, to work.
Ideally, in my opinion, each administration page would have a documentation page outlining options, use case, ect. Module contributors could follow the same guidelines. In my opinion, a wiki would be ideal.
Drupal seems to be a wonderfully complex CMS that I look forward to using more fully in the future but currently I can not easily find answers to even the most basic functions.
There are a number of books
There are a number of books on the market that will help you with understanding Drupal from an enduser's perspective.
--
Drupal services
My Drupal services
--
Drupal services
My Drupal services
Versioning
Playing off the comment about the Postgresql docs (and a similar structure exists for the MySQL): it would be really nice if we had some kind of global core-compatibility versioning for the handbook. Obviously this already exists on api.drupal.org, but as a practical matter, I really don't know how to achieve (and maintain) such a structure for the handbooks.
One think that might help would be a tool (like the clone module) to allow the doc team to more easily make copies of pages.
---
Work: BioRAFT
pwolanin
Yes, that's a great idea, pwolanin !
I am using the clone module on a web site to quickly create documentation that follows the same outline. It's efficient. It saves time and encourages consistency. And the module itself is simple, powerful and quite robust.
Here's what I would like to see and use :
Created by [user name] on [date]
Modified by [user name] on [date] with optional description of modifications
.....
Some already do this ! And I find it very helpful. I tend to trust something that's been updated... and even 'signed' & dated with description of modifications (although not always).
Caroline
Free tags ? (or a large vocabulary)
Also, free tags should be used for the handbooks and recepees... or a large vocabulary.
Now all php snippets are grouped together... all they have in common is... php!!! LOL...
Same with javascript...
I think we need organization by both 'usage' AND 'tools'... the what and the how...
For example, let's say someone wants to improve searching... it may involve themeing, it may involve a contributed module, a php snippet for a block, all sorts of tools... all this is related by the term (idea, feature, web site tool) of 'search'. Sometimes a solution only involves CSS. Imagine this : I get onto a page that tells me how to theme my search box and there's a clickable term called "search" that leads to all doc pages about "search" (as web site tool). Pa-ra-dise !!! I just have to pick and choose. Using a tool (the how) that I may not have thought of.
It is quite superficial to separate things into "themeing" (template engine and overriding theme functions), php, and CSS.
We definately need more concept-oriented taxonomy used in documentation... I think.
The way other large projects do this...
...is store their documentation in CVS. (this is also how the API module works, as well)
When version n+1 comes out, they simply branch the entire handbook for version n+1, and then edit/delete/add as appropriate. Extra bonus is that the entire handbook is downloadable and browsable off-line for whatever version of Drupal you want.
Problem is, that way you only get developers writing documentation, not newbies, business people, teachers, and a number of other people who could write great documentation but don't know how to use the tools. This is fine for something like Gentoo, but not good for something like Drupal.
So imo the "ultimate" solution to this problem is write something to allow book module to interface with a revision control system. It would show a nice pretty GUI to a site visitor, but on the backend would save copies of the docs to CVS (or Subversion, or whatever). AFAIK, nothing like this exists, but we should have a discussion on the docs list about strategy at some point.
Tagging kind of works, but it's annoying because there's no way to pull up "the" handbook for Drupal 4.7, and you end up with these hybrid pages that have all of this "If you're using Drupal 4.6, look in blah blah blah, if you're using Drupal 4.7, look in blee blee blee..."
Just to reiterate though, the only way these things will ever get looked at/improved/fixed is NOT to bury suggestions in a big flame war forum topic, but to post issues about them so people can actually do something about them.
I am a technical writer...
... and I have decided that, once I get my site up and running, I will be devoting a fair amount of time to actually documenting Drupal.
You can get a lot of good help here by asking questions -- people here tend to be very patient with beginners, even when we wind up asking questions other people have asked a billion times. But I agree that at times the documentation can be flat-out confusing.
And of course there are always people who get snotty whenever someone complains about their pet project -- please ignore them. They are unavoidable in any project, anywhere...
Hey
This thread stinks. I'm likely to conclude that the poster of this "Drupal documentation: A constructive criticism" suffers from a short temper for the past 25 years of his programming experience (and mine is only 6). Three months ago, Drupal code seemed like rubbish to me --> I have no experience in PHP, I have no experience in MySQL, and definitely I have no idea what a CMS is.
Furthermore, I'm fairly busy doing work and have no time sorting through Drupal documents. But then I just decided I ask myself the right questions (or phrases for that matter) and used that big Search box at the upper right corner. It really did a lot of good.
In other words, I never give up. :) (maybe it's because I drink taurine -- good for blood pressure and brain function.)
Seriously, if you want to know about it's architecture, start here: http://drupal.org/node/17914
OP has a point
I think you'd be the one with a short temper if you read a post intending to improve the quality of Drupal as a whole and came to the conclusion 'This thread stinks'. The original poster is just pointing out the obvious, it's just like the Handbooks pages, people don't seem to acknowledge that they are a massive uncharted jungle of code and text, the Menu on the left is scary looking for anyone new and impossible to read once you get deep into any section because of long titles.
Your kinda proving his point by saying he should start here: http://drupal.org/node/17914 <- Ver. 4.6/4.7 when really he should probably start here http://drupal.org/node/82920 <- Ver. 5.x version
People have already suggested great ideas in this post that should at the least, be considered, like FreeTagging of snippets, holy jebus, thats ALL we need!
The categories could be:
Language ex. [php, mysql, javascript, jQuery, phpTemplate, html]
Version ex. [4.6, 4.7, 5.1]
Type ex. [page, block, template, module hack, core hack(for all you jQuery 1.1.1 fans)]
Module ex. [BuddyList, PrivateMsg, Views]
I'm sure I missed a lot, but you get the idea. Using that we could filter snippets, I could say I want all [php and mysql] snippets for version [5.1] that go in a [block] and are for the module [BuddyList]. Now isn't that easier than... drupal.org/handbook-of-time-wasting or Searching without even being able to filter out posts older than 1000 years or order by date. Plus it took me a while to even realize these snippets existed, then a bit longer just to see how to contribute some, then a while longer to realize no one would ever find/see my contributions.
Many people say use search but it's not that easy, search doesn't find everything obviously, you can type in "buddylist snippets" and in the list you'll see "Add/delete to/from buddylist snippet" http://drupal.org/node/35738 and it will probably be the first thing anyone clicks. Have fun sorting through which one of the posts contains the correct code for your version, let along working code. Not everyone has the kind of dedication to search all day for the answer, but that doesn't mean they can't contribute to the community if things were made more easily accessible for them.
Take a look at the last two posts there, one asking for snippet update to v5 which no one will probably ever see, and another person asking how to use the snippet in a block. Too bad they can't just filter all the Buddylist snippets for blocks... Too bad we cant see that there are no snippets for BuddyList using blocks and then easily add some to help the community.
It took me a while to find http://api.drupal.org/ , but you can at least get it on the first page of search. Thats like one of the most important pages here but unless you know to search for "drupal api" then you'll have to find it, it's in the handbook buried under:
Developing for Drupal
# Contributing to Development
# Mailing lists
# Coding standards
# Administrators Survey <- wtf (This survey was conducted September to October 2006.)
# List of modules seeking help or maintainers
# HOWTO: Benchmark Drupal code
# Drupal's APIs <- oh there it is, too bad the page already scared me off
It should be one of if not the first thing on the list under Developing for Drupal...
For a jungle-tastic handbook example just look at http://drupal.org/node/21867
The only way to find if what I need is in there is to look through each one, the only way to know what version they are for, or if they've been updated to 5.1 is to click them and read through the posts, why not have that info listed next to them in a table.
I wish the snippets were more like the project pages, where they could be maintained and updated for new versions of Drupal by US the community, then snippets could have bugs in them reported, etc. Instead of a free reign area where you have to warn "This snippet might explode your page, good luck, especially if you have no coding experience what-so-ever."
The main point here is it just seems like Drupal.org doesn't even coming close to using Drupals full capabilities in creating and organizing its own snippet/handbook section. It's just constructive criticism, it should at least be looked into and if its something one of the developers doesn't want to waste time doing, great, then don't. I'm sure they also don't want to work on every module created either, they hardly want to update the forum so comments aren't threaded into each other causing craziness on deletion of comments, so just like the module section why don't we pass on the snippets to someone who will maintain them, the community.
If you build it [a section or a wiki!], they will come. [fill it with snippets]. :D
The only part I don't completely agree with is "Why isn't there an interface for modifying the look and feel of nodes, comments, pages and blocks. Why do we need to screw around with the php stuff?"
Unless I misunderstood what you mean by Interface It gives us more power to customize? I like how the template files work even though I don't fully understand it yet, it gives you a lot of options. That and CSS is how you get the customized look outside of the original Drupal install, you can go wild. I like the fact that we have to edit code (not core) for the look, I want something I can dig into and mess with on that level. I feel like I have full control instead of a interface limiting my ideas, I think making an interface for the look would only limit people in their ability to customize on their own and would end up producing even more copy cat sites, just with slightly different colors and fonts ala 'MySpace' which I don't feel is true customization.
Hey WhatTheFawk
Haha! You missed the entire point bub. Don't try to be heroic.
In capitalism, doing something as a labor of love won't feed your hungry stomach. Producing something great needs financial sponsorship, and that includes DOCUMENTATION. If I have work that feeds me, and work that doesn't feed me, of course I'll PRIORITIZE the former. And that explains why documentation around Drupal sucks.
But since you don't have money to spare, then it doesn't give you the right to complain. Live with it.
Zer AC
Electrical Engineer and Software Engineer
Skunk Works Team
Newhelix Smart Business Solutions (http://in.newhelix.com)
Professional programmer?
And how is it that a "software engineer" doesn't consider documentation to be part of the job?
Nancy W.
now running 5 sites on Drupal so far
Drupal Cookbook (for New Drupallers)
Adding Hidden Site Design Notes
NancyDru
Zer, keep telling yourself
Zer, keep telling yourself all those things. Actually I didn't miss the point and this isn't about money it's about time. Which I and a lot of the community have, as is evident by the massive contributions in the modules section, people are willing to do these things for free.
So why not make the snippet section more like the module section and let the people who do have time, and don't care about money, maintain it. Or start a wiki for documentation of the structure and inner workings of Drupal for developers like the original poster. There have to be people here besides the developers who know that type of information and would submit it if it were easier for them to do so in a more structured way. It would give the creators of Drupal more time to worry about Drupal itself instead of maintaining the sites organization.
You tell me not to try be a hero, all I did was make a post on a CMS website with my opinion about the state of their documentation on the site... If that counts as heroic you might want to check your standards. Also, who says I don't have money to spare? I'll stop 'trying to be a hero' if you stop trying to be a psychic. By the way "in capitalism, doing something as a labor of love won't feed your hungry stomach"... What if I was a professional cook who lived in the woods located in a remote section of the world and had a passion for hunting my own game? Just because something doesn't make or come from massive amounts of dollars and cents doesn't mean it can't benefit people and be of great quality. If you say I miss the point, then next time explain it instead of mouthing off further obscuring the point you say you were trying to make in the first place...
"Producing something great needs financial sponsorship" LOL, give me a break, while I won't disagree that SOME financial backing is needed to acquire the tools you'd need to create something, like a computer or money to keep a site running, things like YouTube, TheMillionDollarHomePage, PHP, NewGrounds, theres plenty more, were started without much if any financial backing and turned out great. Producing something great needs time, effort, and passion for what you are doing, not money stuffed into it. Like I said if they don't want to do it or they have other priorities, then like the modules section they don't have to maintain it, but at this point we have no other options than to search for days in the handbook.
Seems like you're suggesting I just sit and say nothing about the state of things, can you explain how doing nothing will help solve a problem that needs action?
I also don't think the documentation sucks at all, it's just unorganized and very hard to contribute to. Things are here, a lot is documented, it's just really really hard to find.
Anyway I, like you, have the right to complain about whatever I want, the difference is my complaints also come with ideas and suggestions to solve the problem at hand, not a couple of sad attempts at a personal attack, so live with that.
....
Brewing flame war is ended.
Thread is locked.
-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