A week ago I wrote some pages in the Administrator's guide. They don't appear in the index yet. I think it's because they are in moderation, but how long does that take? And if they are not accepted, how will I know? Searching for random nodes I found other contributions too, and not all of them were bad.
Generaly speaking I think the Drupal's community is not working very efficient, at least not seen from users/admins perspective.
- A lot of forum threads end halfway a discussion. Apperently there is no need for discussion anymore when a problem is solved, but visitors may want to know how the story ends?
- Documentation of modules is very poor, the same counts for general concepts of Drupal.
- New contributions and comments generate a lot of content but dont grow towards a knowledge base.
I don't know if what I say counts for developers - I don't think so. But when it's about new Drupal users I take myself as an average example. I created a simple site now. It will cost me two hours of work to do it again, but I invested two weeks on finding out things. That would be acceptable if you needed to learn particular skills to use Drupal, but that's not true. In fact it's been very easy when looking back.
Maybe what I say counts for all internet communities, but Drupal should have the tool to do better....
Carlo
Comments
Documentation team
It's the documentation team's goal to address these issues and to streamline both the documentation and documentation writing process. There is a documenation mailing list to coordinate these efforts. It would be a good idea to bring this to their attention. I'm sure they would be happy to review (and approve) your contributions. If you plan to make more contributions, or if you want to play an active role sorting out these issues, it is recommended that you subscribe to the mailing list.
Either way, I think you contribution needs a bit of work. It could benefit from being integrated better, as this is covered on other pages. Your text does not include links to pages with detailed information about a particular topic (eg. Drupal's node building mechanism). The text does not use proper punctuation/captialization/headings. Also, the text is quite technical, so I'm not sure it belongs in the administration guide.
Some good material
Carlo, I lightly edited your post here: http://drupal.org/node/19828
I think the material is pretty good and left a comment as such in the log. I'll let someone on the documentation team take a closer look at it and decide upon approval. The other two pages didn't seem as useful to me. You can read my comments in the logs on those pages.
- Robert Douglass
-----
www.robshouse.net
www.webs4.com
and Thank You!
taking the initiative to write documentation is always a welcome thing.
- Robert Douglass
-----
www.robshouse.net
www.webs4.com
I made major changes in my
I made major changes in my post, added a log message that explains most. I deleted the content of the other pages (left a link to the remaining one). I also got myself into the mailinglist.
So now I know how things work, but I still find you have to do a lot of effort to get a grip on it. Why are things so difficult to find out?
I mean, I work with drupal for only a couple of weeks now. It would have saved me hours if I had my own tutorial when I started. But how is it possible nobody wrote it down before and/or put it on a place were it can be found?
I may sound a bit negative.
I may sound a bit negative. That's not true. I am not offending anyone. But I wonder if there is something that needs some rethinking to make life easier.
A CMS community like Drupals should be the first to find creative solutions to deal with the problem of structuring users contribution. Until now I don't think the Drupal site is a good example of its own product. I would like to know if others agree with me and if it is an active topic?
.... well, you're right.
You're enthusiastic about Drupal; you're ready to become a master at using Drupal and be an active participant in the community; you want to make things the best they can be; congrats! That's basically what has happened to hundreds of people who are in some way already active in the project. Everyone finds a way to contribute, to make it better. Some fix bugs in the code, some write translations, some answer questions in forums, and some figure out how the whole system can be better. How would you have it done, with the documentation? I personally don't think the moderation features of Drupal are on par with its other great features like taxonomy. You've opened up the discussion, what are your suggestions? Come up with a good enough idea an it is likely (or at least possible) that it will get implemented. The only limits on what gets done around here are time and resources. Every Drupaller I know is working as hard as s/he can to make Drupal better. Glad to have you aboard, Carlo.
- Robert Douglass
-----
www.robshouse.net
www.webs4.com
Book module needs code updates
We've been discussing this quite actively on the Drupal documentation list. Basically, there needs to be better notification of updates of the handbook.
Also, what you write is very much a "How To". There is very limited How To information in Drupal currently. Bryght has written a lot over at the support.bryght.com site.
Your original write up -- How to build a typical website -- is what I wrote up as a New Site Checklist. It doesn't assume what type of site you are trying to build, but goes through the steps you need to in the right order (e.g. pick modules to enable before setting roles/permissions, otherwise you have to go back and set permissions after enabling new modules).
I added comments in the log and also copied it to the dev wiki if anyone wants to refactor further. I'll also point to this thread on the mailing list.
Thanks Robert. You're surely
Thanks Robert. You're surely not saying that the problems one meets are the best motivation to contibute? :-) But thanks for recognizing that my intention is positive.
Boris post shows one of the strange things happening: a lot of important information on Drupal is only found on other sites. In my opinion it shows the system doesn't work yet.
I don't understand the discussion about a HowTo part in a handbook. Every major handbook/helpfile is divided in a users guide and a reference. The question is: where do you search when you have a standard question? I think it's the handbook. A forum is a place for discussion, not for repeatedly asking the same questions and becoming anoyed as an answer. That's what's happening now.
So the effort to make the documentation grow is already there. It's on the forum and on other websites now, so it should be focused better.
actually, I am saying that
I do believe that the problems one meets *are* the best motivation to contribute.
- Robert Douglass
-----
www.robshouse.net
www.webs4.com
Distribution inevitable
One of the best things that can happen to Drupal is that individuals or companies find a way to make money with it. Nothing drives development and documentation better than a couple of greenbacks. Much of the documentation found on other sites is the product of some person's or company's efforts to make money using Drupal. That's why we love Google. The system will never work in a way that puts all Drupal material here. That doesn't mean we shouldn't try to make the info here the best it can be. Most of the people who make money with Drupal (that I know) post articles on their own websites and help improve Drupal and drupal.org
- Robert Douglass
-----
www.robshouse.net
www.webs4.com
You turn it around.
You turn it around. I'm not saying all information on Drupal should be centralised. I say it's illustrative to the problem that common information is only available elsewhere. It illustrates that the problem is not a lack of effort.
gotchya.
I understand.
- Robert Douglass
-----
www.robshouse.net
www.webs4.com
A problem analysis
I think I understand what the problem is. Every open source project starts with one person having a good idea. Only when the fundamentals are ready he makes his project public, and more and more people get involved. I think it is the only way it can work.
As for the documentation project it seems as if the handbook is started from scratch in the drupal community. That's where it went wrong. Everybody has it's own idea of what a handbook should be, but there is no central idea to react upon.
So a solution might be: give one experienced person a mandate to write a well structured handbook. Maybe the person should get payed for it - if it helps finding someone. If you explain the plan on the website and ask for a donation you will get more funds than needed.
When the handbook is ready, let it evolve in the community
Distributed writing
If we start out with a single person writing it, and then move to the community, it will only degenerate into chaos again. We need everyone who works on it to agree from the beginning, and we need good workflow tools to do it. Luckily, this is in the making.
Drupal is simply too big for one person to write about. There is a huge amount of modules, not all of which are maintained, plus there are dozens of different ways of actually using Drupal.
--
If you have a problem, please search before posting a question.
refinement
- I am not telling it should be complete, it has to set the tone and create a framework.
- The problem is not about chaos or structure, the problem is short on common sense (and chaos as a result). As a matter of fact the only way to get common sense is (imo) to have something worth to react on.
- I am not offending any ideology or discussing the merits of distributed writing. I just tried to analyse the mechanism behind it. All good examples have been started by a single person who created the bones.
- Why should it degenerate again? Drupal code doesn't degenerate, and a lot of user maintained documentation on other sites don't.
- Maybe my solution is not the best. But what about the problem? If we agree about the problem that would be the first step.
--
if you have a problem, please keep on trying. :-)
One person starting it
Starting with a clean slate offers benefits in the short run, but doesn't help in the long run. Multiple people need to work on it at all times.
With Drupal core this is the same: each piece of code passes by multiple eyeballs before it even gets near the CVS repository.
--
If you have a problem, please search before posting a question.
But lots of documentation in
But lots of documentation in the handbook doesn't get held up to the same level of inspection. :)
Anisa.
------------------------------------------
www.animecards.org
14,702 card scans and counting!
------------------------------------------
There are more coders than
There are more coders than documentation volunteers. This is the case with almost every open source project. Drupal is also making the transition from primarily a developer used CMS to a more wider audience that doesn't seem to have some of the basic troubleshooting skills that site admins need to learn. By basic troubleshooting skills I mean the ability to setup mySQL, troubleshoot basic web server issues, perform google searches and the ability to ask for help in an informed manner.
-sp
---------
Test site...always start with a test site.
Drupal Best Practices Guide
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
>There are more coders than
>There are more coders than documentation volunteers
I tried to make clear that there is enough effort on creating documentation, but that the structure is missing.
>I mean the ability to setup mySQL, troubleshoot basic web server issues
and my post was not about installing drupal. I know nothin about php or mySQL, but it worked all fine. The problem starts when you are logged in and try to get an idea of how drupal works and how you can become creative with it.
>and the ability to ask for help in an informed manner
it has nothing to do with admin skills that it is difficult to find out basic things. What happened to me is this: I wanted to make an issue list for three people working on a computer program. I read all information on all modules (which is not much), installed a couple of them just to see if they were what i needed. I searched on "buglist" and "issuelist" and more (only found drupal bugs of course). I posted my question twice before I got the simple answer that I needed the project module. Just two more lines in the project module documentation would have been enough to save me two days trying. The only reason that I was so persistent was because i knew it was possible, drupal has a nice issue list. Looking back it was so easy, I could have seen it in the adress bar in the drupal issue list. Would it have helped me if i knew more php?
So please be kind to all people that ask stupid questions on the forum. Don't reply with 'try search first'. People do try to search first but have no idea what they are looking for.
Responsability and courtesy
Dear drupal user,
I am not so old. At the time of email scientific lists, the person who wrote the question closed the discussion by writing a synthesis of the answers. It was not so hard, and most of the work consisted to copy and paste.
Drupal does not so much lack documentation. A lot of forum topics could be included into FAQ. It’s really needed: two much users and topics into the forum. Information becomes more and more volatile and access is difficult.
Sincerely
always write forum conclusions
Thanks Fabrice, that's a real good idea. When you start a forum discussion the least thing you can do is write a conclusion and make it available on a location where people expect it.
6 statements to get the focus
- setting up Drupal is not difficult, the difficulty begins when you try to build the website you need.
- there is enough writing effort in forums and on other sites.
- people who start a forum discussion should write a conclusion too. That conclusion should be indexed somewhere.
- the admin's guide should be divided in a reference manual and a users guide, with a clear predefined stucture.
- module writers are the first people that should write a topic about features and purpose. If it becomes possible to add comments it can grow.
- The documentation skeleton should be written by one person. Someone has to set the tone.
Collaborative Writing - Technical Documentation
In my short experience with "collaborative" writing for software projects, I've found out that the Wiki concept is really useful. It allows anyone to create, edit and refactor content, there's no "authorship" (open license for content must be applied), has content revision and uses a simple and easy to learn markup (formatting rules).
What I miss in Drupal's Forums and Handbook is the part where open content is aggregated, to be discussed, refactored and be used as a final document. With a "kinetic" project such as Drupal, the documentation is always trying to "hit" a moving target, and that's hard enough. Any tools or mechanisms that allow for more people to contribute, in a easy and fast way, is useful.
The problem with forums, is that if I don't really know the better terms to search for I end up with an empty search result or a too vague search result. That will trigger me to create yet another entry about what's probably in several other posts. And instead of having a "begin-to-end" document I will end up with a start, several comments as the "middle" and many times no end (although Fabrice points out a valid and useful procedure to close up forum entries). Many times, in several distinct forum entries, I see the same content more or less. Wouldn't it be more helpful if all those entries would be "merged" into just one? Usually Wiki pages work like that: they start from an idea to be discussed, several minor content editing and refactor steps happen and in the end there's a valid fully structured document, created by the community and to the community.
The problem with the handbook, which can work nearly as well as the Wiki concept, is that it's not easily "open" to everyone to participate and collaborate. The structure is "rigid" and must be "learned" in advanced by new readers. The content flow should be fluid, linking pages (nodes) in several ways. The Previous and Next plus the Printer Friendly features of Book module are great, and for this reason plus many others I recommend that the Handbook is the final target for documentation: the place where anyone will find the answer to any doubt, with a complete and up-to-date content. But to reach that point, I see it easier to achieve by opening up a WikiSite then trying to adapt what's done to what needs to be done:
- the documentation skeleton of the handbook should (must) have a team in charge of it.
- the content of the handbook must be final, after content reviewing team published it from open and collaborative sources.
- module writers and other users should (must) have an easy and simple way to kickstart the technical documentation, and allow the community to collaborate on it.
- draft and soon to be published content should (could?) exist in a site that allows for multiple editors to easily create, edit and update content.
I'm "bashing" on forums specially because I spent too much time searching for previous posts that may relate in any way with a problem in hand. I "bash" a bit on the handbook because it's hard to navigate straight to the content I'm looking for, without an easy way to let others follow the path I've just learned.
Does this makes any sense, or am I too off-topic here? This same node would benefit alot from "living" in a WikiSite. Many open-sources have discovered the "flexibility" and documentation boost improvements that wikisites can bring. I hope the Drupal community discovers the same benefits, soon.
Thanks.
^.^
I never thought I would ever be posting from the inside of any issue!
It's not that everyone isn't already aware of all the problems ya'll have outlined, but they are stuck on how to implement it. For example, the closest thing to a wiki right now is more of a wiki text filter, and doesn't really have that versioning functionality. Are you going to integrate the wiki? Who is going to work on the code? Etc.
Anisa.
------------------------------------------
www.animecards.org
14,702 card scans and counting!
------------------------------------------
Rivena,
Rivena,
I understand that, and the reason why I'm working with Drupal and not other FOSS CMS platforms is because of its code quality and the fantastic group of users around it. This to say I really appreciate all efforts that everyone is making around Drupal.
Your comment thus however raise a point: who is stucked at which functionality? Who would appreciate any help or even a "virtual" brainstorm? What's the "official" comment on Wiki-ism around Drupal? Where can I find that information?
An open participation, without using this "threaded-comment-mode", would be very helpful. If you can, please evaluate the information quality around Ubuntu WikiSite, which I consider a very good example of how high the quality level of documentation produced in a collaborative manner can reach. There are many other examples, likes the ones pointed out by other users in this and other threads. But I know of no example, based in Forums, that can reach the same quality and be as much user-friendly to "newbies" as a WikiPage. I assume that many of us are no coders, and would instead give a try to improve the current documentation, if and only if that task would be simple, intuitive and practical. I bet (presume if I may) that Drupal's documentation isn't getting as much commitment from the community as it could if a new mechanism would be put in place.
Note: Drupal already as a simple Revision Control mechanism for content. It could be improved to reach the same level of "standard" Wiki-mechanism. But what I miss the most is the easy-editing (possible with QuickTags, maybe) and easy-linking of nodes, not to mention the simplicity of inline-media attached to a document that most Wiki-GUI editors provide.
hm. Okay, so, and this is
hm. Okay, so, and this is without saying I agree or disagree with this, most development is done on the devel mailing list. Recent discussions on improving the handbook have gone on in docs mailing list. Both of the archives are available online. Go to Support > (any) Mailing List > Archives.
Drupal documentation doesn't have as much committment from the developers. This shows up in loads of areas.
I do not believe that the documentation has to be in a wiki, easy to edit format to be accessible and easy to understand. I believe it has to be written by people who know how to write in an easy to understand way.
To answer your questions, currently, it'd be nice to see improvements to the book module. Some suggestions were made, but not taken up by any one who can actually implement them. You could look at my issue posts or search the docs/devel list. The docs team would appreciate any input you have. You can sign up to the docs list and discuss it.
I don't know what the official comment on wiki-ism is. I think they (they being developers :) liked the idea of a LaTeX or DocBooks style thing for documentation, but it's pretty complicated stuff.
Right now we've given up on getting improvements to the book, and are looking to improve the documentation. Help is certainly needed.
As a bit of advice, and this is not saying I agree or disagree, here, at least, people listen more if your suggestions are backed up with a concrete idea of how to implement them. The idea being anyone can say I wish or I want, or it would be better if, but it is not as constructive.
Anisa.
-----------------------------------------------------------
Kindness builds stronger bonds than necessity.
www.animecards.org - 15,000 card scans and counting!
-----------------------------------------------------------
I completely agree about the
I completely agree about the wiki, having spent almost all my free time in the last four months trying to learn Drupal/Civicspace. Wordpress has a great wiki site running on Media Wiki for collaborative documentation and it really works: http://codex.wordpress.org/
While the Drupal forums have been of great help and the people nice, there are plenty of doubts that are still unresolved. Just the other day, I had to delete and do a fresh install of Drupal because anonmyous users couldn't see any content on the site- by that time, I had spent close to two days searching in the forums. I actually bumped up a one-year old post as it was the only complete one among hundreds dealing with my search term. The posters who tried to help me did their best, but although I tried their suggestions using both command line and phpmyadmin, it didn't work.
I just want to say that a wiki might open up participation in a greater way