I'm often searching drupal.org for the solution to what seem to be relatively common issues, but nearly always, they are really hard to find. I have a feeling that this is mainly due to the node/comment setup of drupal, combined with the huge number of posts on this site. a good example is upgrading from 4.6.3 to 4.7.4.
a wiki site would be extremely useful for documenting drupal. the inter-linking and flat (non-hierarchical) form, and ability to easily edit and update pages makes it really simple to create a concise documentation for such a project. it would also reduce the amount of duplicate questions on the forums.
just looking at http://drupal.org/node/102913 , and it seems that it's not extremely simple to set up a wiki within drupal at the moment (but I agree, it would be a great feature later). perhaps it would be good to set up a standard wiki installation (mediawiki?) at http://wiki.drupal.org/ ? if at some point drupal has a working wiki solution, a bot could be created to transfer the pages back into drupal proper?
what do people think?
Comments
Wiki or not!
A real Wiki could make the documentation easier to structure, update and browse. Who knows, maybe the folks running Drupal.org will add one.
However, Drupal's Handbooks are made using the core Books module that replicate in part what a wiki does. Books can be maintained by a group of users and can be browsed through a list of recent changes. Projects team members can integrate the content of comments inside the main documentation, if they want.
Drupal is growing up fast. Maybe handbooks contributors do not have time to update everything.
To help with the documentation you may have a look at these links:
http://drupal.org/contribute/documentation
http://drupal.org/node/23743
/*_*/
http://www.xmacinfo.com
yes and no
First, I'm all in favour of any input folk can have to improving the documentation,
but as an opinion piece ... I think that wikis are a cop-out solution to structural problems. Just like FAQs can be a grab-bag of 'information' that the site editor couldn't figure out where to put, trusting a wiki to structure itself is an information architect just throwing in the towel.
The wiki-style structure inside pages with its subheadings and TOC is great, and should be replicated, but the wiki-style lack of positioning in the site would not help make this documentation any more usable.
We have books, we have sub-sections, we have an attempt at structure, but yes, sometimes related topics are spread around the place.
The best contribution a casual contributor can make at this point is (I think) to add comments with cross-references to related pages, either inside Drupal.org, to Drupal forum threads or even off-site tutorials. Preferably titled appropriately and maybe with a teaser quote. a link to ... /node/23743 may be appropriate and contain useful reading, but it's not very friendly or informative for clicking on.
So we end up with book structure that still works (and the publishing cycle that's built into that), and better cross-referencing to the more hard-to-find docs.
It could also be a suggestion to add tagging to the docs! ;)
.dan.
How to troubleshoot Drupal | http://www.coders.co.nz/
.dan. is the New Zealand Drupal Developer working on Government Web Standards
Re: yes and no
"The best contribution a casual contributor can make at this point is (I think) to add comments with cross-references to related pages, either inside Drupal.org, to Drupal forum threads or even off-site tutorials"
but that's exactly the problem! the fact the the answers are everywhere, and incredibly hard to find.
I think it's absolutely vital to keep the current book-documentation structure, but i think a wiki could complement that hugely.
the structural problems of the wiki system decrease as it gets more users. the more people using it, the more the interlinking works, and makes it easier to find things. if you're talking about the lack of heirachy within a wiki, then I have to disagree - not all information CAN be confined properly within a heirachy, and for general information, I find wiki the easiest method of continual documentation I have ever come accross (I now use wikipedia instead of google for simple net searches). of course, the more valuable information from the wiki could be transferred into the book structure, and vice versa. safety in diversity.
Both worlds
You're saying that wikis are superior in the respect that their interlinking and cross-referencing makes for a better or more useful navigation.
Cool, that does help, especially in this case.
I suggest that we add more and better interlinking to the pages we have
thus gaining that wiki advantage at no cost or upheaval.
While a heirachy may not directly help when troubleshooting one distinct point or subject, I think sequential reading DOES help when actually learning or reading the documentation to see answers to questions you didn't ask, or understand the beginning and the end of a subject. Sometimes you do have to RTFM ... and come out better from it. With wikis, I never get the feeling I've seen it all, because some pages can be inadvertantly 'hidden'
There are tutorials, (that IBM page is gold) that can be read through, and there are reference documents (php.net) that are easy to dip into ... and the docs here are both.
.dan.
How to troubleshoot Drupal | http://www.coders.co.nz/
.dan. is the New Zealand Drupal Developer working on Government Web Standards
true
basically agree with everything you're saying. it's just that some things can almost never be found. (perfect example at the moment is differing file permission setups - http://drupal.org/node/26635 is a start, but doesn't work with my server).
it would be good to add more interlinking to the drupal docs, but that's quite difficult at the moment, especially as the people who see the linkages between certain pages aren't necessarily the people who have permission to add those links to the existing pages. comments aren't appropriate, as you have to trawl through them, and they are completely unsorted, which makes things really difficult.
your response title says it all - "both worlds". the wiki could be good for a sort of documentation scrapbook - and as a resource for the official documentation, in drupal books.
levels of participation
"Maybe handbooks contributors do not have time to update everything.
To help with the documentation you may have a look at these links:"
that's the point, I think - the main documenteers have too little time, and I, and probably nearly everyone else, do not have the time or resources to become a proper document moderator. I already get about 15 emails a day from various list, and I know very little about drupal really, and don't have time to learn it all. BUT I definitely have a few minutes a week to write up a few sentences or add a couple of links to a wiki about the little bit I DO know of drupal, or related modules, or whatever, and I bet a lot of others do too.
this would take a load of basic work of the main document maintainers, and would make it easier to update the official documentation. you might even find a few new people keen to help out with the official pages.
Try Google. Google tends to
Try Google. Google tends to come up with more pertinent answers to a query than the drupal search, but I'd say that Drupal search is much more improved now.
Google's use of referencing links probably helps here.
I think a separate wiki would help, so would links to good offsite material like http://www-128.ibm.com/developerworks/ibm/osource/index.html and longer descriptive urls.
One approach that might be useful would be allow users to edit queries they have posted to add keywords they consider most appropriate that could help search engines
Offtopic, but...
This is offtopic, but I even opted to completely do away Drupal Search and simply use Google Search (Google Co-op actually) instead, it offloads the server and is more accurate. The only downside is that you can't search ALL content, because sometimes google will still have to index it. But when your site is fairly big and you're using sitemaps, then that shouldn't be a problem either I think.
I looked up the Google Co-op
I looked up the Google Co-op and it appears to be a great idea, perhaps a group of Drupal users can create something similar for key search phrases in Drupal, based on a general faq and faqs for specific areas of Drupal.
Wim, can you show me an
Wim, can you show me an example of how you use Google Co-op?
sometimes
yeah, I use google after searching drupal.org, but it's still hard to find stuff, due to the fact that google list contents by popularity, and not all the things I'm looking for ARE popular.
wiki is also a great way of creating link pages - which could easily interlink to external tutorials and help pages.
if such a wiki were setup, it could easily be indexed by google anyway, adding to the possibility of finding things.
I like your last comment - I think it would also be great to be able to freetag comments - that would make things much easier to find.
interlinking:
interlinking:
this solution would tie in nicely with:
Proposal: How to get more people involved with documentation
http://drupal.org/node/67367
there is an feature request posted here:
Proposal: Drupal documentation wiki
http://drupal.org/node/105915
...
We are not using a wiki for our documentation. We are stuck with out own dog food. Exporting content from a wiki also often gets you invalid html, etc.
Currently anyone registered on drupal.org can contribute a handbook page and edit what they contribute. People with document maintainer rights can edit and update the vast majority of the handbook (selected pages are locked) and these create node revisions. No one has updated the diff module in quite some times so that is out as an option for us but is needed for a more closer wiki like behavior. People with site maintainers role can do additional work in the handbook but that is rarely needed. We have a mailing list for communications and issue queue for the rest.
We used to have more 'interlinking' but it quickly grew unwieldy, cumbersome and prone to link to unpublished or old, out dated information. At last count there were around 1400 pages in the handbook and interlinking them is problematic and a maintenance nightmare unless someone has come up with some better Drupal tool I haven't heard of. There is a restructuring proposal on the doc list archives which has received some feedback and is the direction we will be going if you are interested in helping out..
Click the Contribute tab on the top of the site, then click the Find out how to help with documentation link for more ideas on how the existing process works.
-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...
the problem with the current system is that it's too intensive. if you want to get involved, you have to get completely involved, and write a whole page. you can't simply add to or change a page (you can comment, but it's not the same0. this definitely discourages some users from even trying.
exporting from a simple documentation wiki (mostly just texts and links) would cause few problems. a couple of bots could be set up to do it automatically for the most part...
there were around 1400 pages in the handbook and interlinking them is problematic and a maintenance nightmare unless someone has come up with some better Drupal tool I haven't heard of
wiki solves the problem with interlinking by letting anyone find broken links and fix them. ofcourse it would be better to use drupal for the drupal site, but the tools aren't available (see link in the first post). wiki is available.
IMO...
I don't see any problem with contributing by commenting. It works fabulously on php.net with all the user-contributed examples, gotchas and tips. I guess some moderation makes it work so well.
OTOH, I personally am nervous about using a wiki where I may rephrase someone elses input in a way that may not be appreciated, whereas I find adding a stand-alone paragraph of my own is more clear-cut. I guess I'm just not immersed into wiki-think.
.dan.
How to troubleshoot Drupal | http://www.coders.co.nz/
.dan. is the New Zealand Drupal Developer working on Government Web Standards
...
Are you interested in joining the documentation team? I've provided the links on how to join in my post. Does it say you will be required to write entire pages if you join the doc team? No. It says if you are not interested in participating in maintenance then you are free to contribute solutions (complete pages) but if you want to do more, join the docs team. Is that a barrier? Not really. It takes very little effort to do this.
If we truly need the tools, then perhaps we should develop them. In the meantime, wiki's are good for developers but they really do require a serious learning curve to learn the irritating markup language which I consider a higher barrier.
In the past, for various temporary documentation tasks I've set up a scratch Drupal site and used the book module to good effect there. We then removed the site when done with it.
-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
not enough levels of interaction
not sure it you read my post properly, but basically what I was saying is that there not enough levels of interaction with the documentation.
the current levels, in order of least-to-most-intensive are:
* no involvement (reading only)
* Commenting
* writing whole pages
* becoming part of the team
but I (and, I imagine, many others) don't have the time, knowledge, or resources to do either of the more intensive two options. I do have time to comment, but I don't think it's incredibly effective, as it looks out of place, and isn't as coherent as having all the information in one page.
Ideally, I think this would be good, again in order of least-to-most-intensive:
* no involvement (reading only)
* Commenting
* wiki
* writing whole pages
* becoming part of the team
I also have a problem with the current hierarchy set-up, I can rarely find the thing that I'm looking for by clicking Handbooks>Section>Page. I usually have to search. I guess that could just be me though. wiki can get around that (although using a multiple hierarchy setup in the handbooks would too).
ideally, it would be good to have a wiki-like pre-official doc setup within drupal, but that's not possible at the moment.
...
You seem to have a conceptual misunderstanding of the time the last two actually take.
You've spent more time arguing to add an additional step and an additional place to check for content to the process then actually participating on the doc team. Adding a wiki would actually add a tremendous amount of work to the already small existing pool of volunteers as someone willing to actually bother participating would have to take the time to transfer the content of people not willing to actually participate. Or, everyone would ignore the wiki and it would be unused. Additionally adding a wiki to drupal.org would mean yet another website to maintain for a very small pool of volunteers who do this already.
Any registered user on drupal.org -> The existing is write content, it is published.
Any registered user on drupal.org => file an issue with alternative content.
Handbook maintainers -> edit content, it is published.
Handbook maintainers -> file issue to remove comments if you have added content of comments to handbook page so a site maintainer can delete them.
Handbook maintainers -> add content, it is published.
Two steps for pretty much everyone.
Anyone can propose a different structure though there is actually a reason for the existing structure. I mentioned a proposal to change some of the handbook structure for installation and configuration. It's on the doc list archives if you are interested. Of course, that does require more participation. You are essentially proposing additional work for others while firmly stating that you are not willing to do any additional work yourself.
I'm often in #drupal-support, feel free to ping me at some point.
-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
--
Long ago, Drupal.org should have switched to Wiki for its documentation. But like someone said it here, we're using our own "dog food", partly to test it, hence we're using "Book". But what about http://api.drupal.org/ ? Is that the book module ?
If you want to blog, don't use Drupal, use Wordpress.
If you want a forum, don't use Drupal, use phpBB.
And if you want documentation use Wiki.
I agree that finding documentation is hard...
I most often find solutions by fluke in here. And through asking questions of course.
The great quality of wiki documentation is due to how it functions, not the people.
We are not here dumber or smarter than people who contribute to wiki... due to how wiki operates, documentation can only get better and reach the quality it does...
Everyone becomes an expert with a particular issue, then... what ? You cannot really "edit" the documentation here, as Mr or Mrs Joe Blo who really knows that something tiny... that's new or better...
I think it's ok to tell someone : you are right, but there's too much to change around here for that, and I don't feel up to it and suspect that not many others will...
API
Nope, it doesn't use the book module.
That site is automatically generated (using http://drupal.org/project/api) from comments in the source code, plus the odd HTML tutorial page kept in CVS. Generally the barrier for editing that content is a little higher than editing the handbook as you either need CVS commit access to those files or in most cases to supply patches for someone else to commit.
--
Anton
New to Drupal? | Forum posting tips | Troubleshooting FAQ
...
Not quite sure what API module has to do with anything. It does something different then the book module so isn't really relevant to your case. API is a Drupal tool that was developed to help get work done more easily. It is a tool that relies on properly documenting the code of Drupal. It is one of those tools I mentioned in passing though not in name and is a Drupal site so not a relevant example except in supporting my comments earlier.
I've already said we're not using a wiki for our handbook and supplied several reasons as well. It would be additional work for very few people, it doesn't make use of our own tools so we have no incentive to improve our own tools, and it's content is not integrated into our site.
I've said this before and I will say this again, if you join the doc team and I assign you handbook maintainer role, you can edit the majority of the handbook with a few exceptions.
I extend to you the same offer I extend to everyone that puts forth your arguments. Do you wish to join the doc team? Are you willing to actually do work in your spare time? All you have to do is ask on the documentation list. I look forward to your request.
People complain that 'finding things is hard' and then say they are not willing to help. That's fine for them to say but doesn't actually get stuff done.
-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
It is a good philosophy that
It is a good philosophy that Drupal maintainers should want use their own tools where documentation is concerned, but if there is not much demand for the book module outside the Drupal organisation, where will the incentive to develop it further come from?
The book needs of Drupal organisation may not be enough to give the book development the impetus it needs, given all the other pressing needs in Drupal.
I have to admit that I am not really the position to make that judgement.
...
Lots of people use book module. There were some improvements suggested before freeze but they didn;t get in for a variety of reasons. Several people have plans for working on it for Drupal 6.0 release. Abstracting it's features out more to make it more flexible.
-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
Wiki or not - Part two
For me Wiki and Books are the same: I can write whole page or update only a few lines. For Wiki or Books I need to be part of a team.
If ever Drupal uses Wiki, it will be set up as to require an account with the right access level. A simple Drupal account won't give access to edit documentation.
The current book hierarchy is not a reason to ditch Books and replace them with a Wiki. Furthermore, a wiki does not make everything structured perfectly. I've seen so many orphaned wiki pages that I would not called Wikis structured. In Wikis, you need to put a big promined Search field on the home page.
So, why replace a tool by another one that does the same thing?
Books will eventually be upgraded to offer more. As well, documentation structure and content will be updated.
/*_*/
http://www.xmacinfo.com
does the same thing?
I wouldn't say that they do the same thing.
half the point I'm trying to make here is that anyone - even non-users, or normal drupal users could edit it.
I can't put it more simply than this: drupal's documentation is convoluted and confusing. if you want an example of really good documentation, check out http://www.mediawiki.org.
naught
Confusing documentation
I do agree, documentation can be:
See : http://www.mediawiki.org/wiki/Database_layout
They say :
Wikis do not solve this age old problem.
/*_*/
http://www.xmacinfo.com
right
but it's the "please help if you are able." bit that's important.
still waiting
for you to join the docs team.
-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 Steven
Steven, you have a knack of attracting people into your team. ;)
Are you "head" of Documentation ? You sound like you are. That's why I ask.
yes
-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
How does a wiki differ from Drupal books?
Can someone please explain the fundamental differences between a wiki and what we have?
The ability to make the docs book editable by everyone (all authenticated users) is possible (though deemed undesirable), just as some wikis have sign-in and required permissions to have edit privileges.
I think wiki provides free linking and makes this easy by suggesting links? Some I've seen have (automatic?) paragraph numbering and table-of-contents generation. Others have a discussion tab where proposed changes are hashed out prior to implementation. But these are all features which it seems our documentation book can probably live without.
There must be something more driving the recommendation to adopt wiki. What's the real difference?
Thanks, Karl
..
Book module has automatic table of content generation. It has revisions. We can use comments or issues (preferred) to hash out proposed changes. Multiple people can edit the handbook pages. Any registered user on d.o. can add a page......
The apparent difference is the complete disregard for existing processes and a desire to use third party tools which would force all 354 existing contributors to learn a completely different system that can already be done within Drupal. Not using our own tools will also offer us no incentive to explore and learn it's weak points so devote no resources in improving it either.
At this point I've stepped hoping for contributions from this thread.
-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
Revolutionary proposal?
I have made a post - A Revolutionary proposal for creating documentation relating to this topic in another one Drupal documentation: A constructive criticism.
Read it and share your opinions on it.