Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.
By ethos webmaster on
Ladies and Gentlemen,
In my first post ever to the Drupal.org forums and as a new user, I initiate this forum discussion to address a number of organizational difficulties I have encountered in attempting to implement Drupal for my general use. It's also a bit of a test to see how quickly I get flamed by "real contributors" for my obvious ignorance, as I have noticed on a number of other topics. Let the games begin.
First, let me say that I think very highly of Drupal and the development decisions elected by the community to make it what it is. Second, let me go on record as saying that I do not know the history of Drupal, I haven't been here from the start, and I have no vendettas against anyone or favoritism towards anyone else. Finally, for all its potential, power, and extensibility, it seems that the project's major flaw at this stage lies in organization.
The Drupal community is very much an organic one, it is obvious, which serves the project well. A certain democratic anarchy is good in a forum-run environment like this, so that everyone's views get expressed. At the same time, such an organic community can easily get derailed or experience growing pains when new users arrive and become daunted by the sheer size of the body of work they are diving into. Add in the typical forum flame wars and miscommunication issues, and we have a big mess, a whole lukewarm pea-soup sea of information just waiting to swallow up valid, useful ideas.
Organization is important. This we all know, to some extent. Organization is more than simple categorization along broad lines or categories. Sometimes it involves condensing the tiny nuggets of essential data from the large amounts of non-useful information that go rolling by us in the lukewarm pea soup. Almost all of us do that automatically, without thinking, filing away little nuggets of data to use later. Almost all of us would rather not have to. Almost everyone would rather be able to simply go idea shopping and quickly find what we're after, whatever nugget that may be.
So, the question becomes: How do we get to the nuggets? There follows: What do we do with the nuggets once we find them? And thereafter: How do we make it so that others who need those nuggets that we find can find them without a pea-soup-resistant wetsuit and SCUBA gear?
I think we're all well aware of the current answers to those questions. Unfortunately, these answers all involve our own virtual SCUBA gear, our own virtual goodie bags, and our own personal list of people to share those goodies with. It's unfortunate that some of the goodies I may have collected in my bag are exactly what one of my fellow pearl divers is looking for, and I'll never meet them simply because they got lost somewhere in the pea soup.
Therefore, let's discuss methods by which we can all organize the nuggets we've encountered and share them with the community. And let's avoid the usual negativity associated with proposing new ideas outside-the-box thinking. Remember, after all, that anything is possible if only we admit the possibility of all things. Yes, that's a little too zen for many people, but suffice it to say that we should not allow ourselves to limit our possibilities. There are no limits.
I look forward to the discussion.
David Rogers - ethos webmaster
Comments
How do we get to the
I think that "new" nuggets of useful information will be only found by brave souls wading into the pea soup. That's what the fora are for--to work out problems/solutions.
If you think that the nugget you found would be useful to others, add it to the handbook--a place where almost every page consists of useful information distilled down to it's most understandable/concise form. The handbook is where new users or experienced Drupallers looking for answers should start, which is why module-specific handbook pages are now linked to in every Drupal installation for real users who need more help.
The PHP snippets section of the handbook is a perfect example of people collecting very useful nuggets of code that may (or may not) be useful to other people.
Keep improving the handbook. If you see a page which is poorly written, take it upon yourself to either correct it yourself or file a detailed issue against the documentation. Not "the handbook could be better," but "the blog module handbook documentation doesn't clearly tell users how to..."
Hope this gives you and others a few good starting points for making a difference for Drupal.
b
umm...
how do we turn off "verbose output" on forum topics? =) Anyways, I understand your point and your post (even though it took awhile to read). The answer you are going to get from this community is -> "look at the handbooks". The handbooks are the place to put those "nuggets" of information and is where you should find them. Yes, there is some lag with the currency of documentation and its not always 100% comprehensive, but that's why you can do a search on forum topics and ask your own. Anyways, I do agree that some additional efforts could be made to make groking drupal faster and easier. One bottleneck that I see is that the handbook entries are not open for people to easily contribute to. I shouldn't have to file an "issue request" for documentation, I should be able to correct it, add to it, etc. While I understand the need (and the argument) to eat our own dog food, I also think you should use the best tool for the job - and personally the open, collaborative, public nature of the drupal community doesn't fit the closed, controlled workflow imposed on the documentation. I would like to see some sort of wiki for the documentation. I also think that documentation needs to be tagged by version as well (this *is* starting to happen). Maybe it makes sense for end-user documentation to be controlled (like creating content and changing passwords) but administrative and developement documentation should be open in my opinion
--Ryan
--Ryan
Ryan Cross
James Cross Construction Services
Project Management Software
The problem with handbooks
There's one tiny problem with that, to be honest... And I'm not trying to insult anyone here at all. But the reality is that a lot of the handbook entries are, well... poorly written. Perhaps this is because the person writing them is just so intimately familiar with the handbook topic he is writing about that he can't get outside his own brain enough to see what a new user would need to have at his fingertips. But whatever the reason I would argue that these handbook articles could use some improvement. I'd like to see more guide sections written like this.
I agree
I totally agree with you. Most of the handbooks are just "fluff" and doesn't really get you any farther than some descriptive text already available in the help areas. Here is a book page I just contributed earlier today http://drupal.org/node/63456 (hopefully you can access it) I'm sure I could've revised it to make it a bit clearer and more "formal", but I figured this was a good compromise for my time. Also, as i mentioned in the post above, if the handbooks were open for other people to edit, then someone else could help clean up my writing and even elaborate in areas if they wanted.
--Ryan
--Ryan
Ryan Cross
James Cross Construction Services
Project Management Software
than start writing them.
If you want to see them, then start writing them. Open Source software only grows throught the contributions of people. THat page is new. I encouraged the person to take his forum post and make it a child page. He did so. You now benefit. Please do so for other modules and configurations you wish to see and have experimented with. Parts of the handbook are 5 years old. FOlks edit and update tham as we find them and we can. Print it out, it's around 1000 pages. Actively there are only about 5-10 of us doing things at any given time period.
You can start getting what you want by contributing now. Any module in the handbook have insufficient how to? Then add a child page and write it yourself.
lectric did and now he is listed here: http://drupal.org/node/14205 and has all our gratitute for contributing to the solution. You benefit, we all benefit. All it takes is people contributing documentation instead of standing idly by and talking about it. Pick up the shovel and join in. I started with the best practices section and kept going. I look forward to your contributions. Please contribute to help those that come after.
-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
Question
Hey Steven
I've seen this type of response from you quite a few times now. As you can see, I try to practice more than preach. Just an idea/question. Maybe it would be useful to some how create a pool of "resolved" issues from the forums. There are a couple of ways this could manifest, either by closing threads and moving them into some sort of que to be summarized/condensed into the handbook. Another example, that I'd like to see is taking the "Showcase" forum and putting a sticky on there basically requesting that if you're going to put your site up in the show case you also should include what you did and how you put it together. Also, could comment on the idea of allowing people to edit documentation? without everything needing to be approved?
--Ryan
--Ryan
Ryan Cross
James Cross Construction Services
Project Management Software
answer
You mean answering the question with how to contribute? Providing an example of this contribution? Begging for people to add the benefit of their experiences to the 'nugguts of knowledge' otherwise known as the handbook? I am trying to help direct them to resources, links and methods on HOW to achieve their 'stated' goal....' Contributing to Drupal'. Most do not ever contribute. That's all right though, because in enough of these threads we pick up one or two people who do. It's worth the risk and the really nasty emails I get from very angry people.
There is an issue tacker for Drupal documentation on on the Project page.
Click the 'contribute button on the top of the page, the 'Help document Drupal' part has three links to documentation team resources.
I agree, if you are not involved in the Drupal community then it can be hard to track who does what. However, I, myself do not have time to track who does what and write it up for other people so that they don't have to get involved. In the few years I've been here, no one else has either. The short answer is... Dries is in charge. Depending on the area, there are then influential people. If you have an area you are interested in, then get involved and you will quickly pick out who these folks are. As you help out, then you will gain a reputation as someone who produces work and often get asked to do more or certinaly get asked if you are interested in joining hte various short term ad hoc teams that spring up and die out as things get done. If you are confused, you ask. If no one else is working on it you get to.
On to forums... to do this with forums, forums module will probably need patches to improve it's capabilities with forum moderators and such. So far none of the existing active contributors has found the time or had the interest to do so. So far a few of the new contributors have gotten distracted by other projects or full time work. Dries has said many many times all it takes is for someone to start submitting patches and he will review them. The submittor needs to review comments, revise, repeat until committed. There are a lot of people who can help them, but do not have time to lead the work to do this. I know one person who plans to try to for 4.8. We'll see if he has time. Maybe you can beat him to it?
If you want to pursue the forum moderator work up an idea and present it. The handbook has how to present change to the community. It just takes people willing to do work and time. We used to move forum threads intot hehandbook, but over time that proved unweildy and confusing to folks so all the forum threads were moved out and their content moved to book pages. I am not against it and certainly have closed occassional old threads at tiems. I have converted threads into page. In fact I have often created a handbook page and then answered with a link to it.
As to adding forum posts to the handbook... I do and have but I cannot do it all, nor can any of the current contributors. Adding a page takes time. So yes, you will see me and others add a post at times asking people to contribute. This is for two reasons, the person should get the experience of contributing, if they like it, then maybe they'll contribute more.
Even with moderation we delete a couple spam pages per week in the handbook. Completely unmoderated handbook pages is an invitation to disaster. There is discussion to open up editing with the edits going into moderation but there is a behavior problem we need to work on with the book module and revisions and pages getting unpublished that needs attention. Also, I have had among the worst workloads in my paying job in the last 12 weeks as I have ever had so have not been able to pursue this as I want to, hopefully soon I can spend more time at home with my wife and kid and Drupal. There are some discussions in the doc list archives if you are interested. I imagine it'll get done in the next few months.
-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
If you want to see them,
I totally understand and agree with this... I try to contribute in whatever ways I feel competent enough to... which at the moment is responding to the occasional forum thread.
However, it's also true that a person can have no earthly idea how to do something, look at the "help" page, and know only enough to know "that page was not any help to me." Just because I didn't understand someone's article doesn't make me competent to re-write it so that it's more helpful. Sometimes the best one can do is flag something as, "I don't get this at all" and hope someone who does get it can step in.
Add child pages as you do
Add child pages as you do understand then. If you can elaborate or extend we're more then willing to replace some of the pages. We do try and go through and review comments made on a page that explain better and incorporate those cmoments into the text as we can. This link (http://drupal.org/handbook/comments) is useful for finding this. When it was first setup I think the average comments on pages was near 50 with some 80-120 comments long. Several of us spent a marathon month stripping things out and incoroporating comments into text. There is still more work to do as it will never really be done so more hands working at it is good.
Being new (and people don't seem to get this) you are in the best position to expand on what you feel is missing on a given page or explanation. You know what was hard for you that you had to work at. Of course, what is difficult for one is easy for another so both points of view are certainly posible if different people write up different pages. But only if the words get written.
Convincing people to contribute to Drupal.org is one of the things I work at. This means that hopefully we gain quality content that is centralized here for peopl to find. I think my current goal is 1 in a thousand. :)
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
Thanks. I needed that... >)
Yes, I'm known to be a little verbose, but I'm also very good at being precise with my language... Which happens to make me a good candidate for the Drupal tech manual, incidentally. Now, while I appreciate everyone's opinion on the matter, I was merely attempting to spark discussion, not ask a specific question.
Yes, the site documentation would be an excellent place to file all these little nuggets of information, but doesn't anyone else think that said book is lacking a heavy dose of organization? What can be done about this? What sort of organizational scheme could we or should we apply to the random snippets of information scattered across the book? Obviously pertinent version information would be helpful, as Steven (sepeck) has pointed out, but is there an easy way to sort pages by date of entry or revision or something similar, such as is readily available in our favorite wikis or CVS? What about sectioning, chapter organization... I feel that the book should take an approach similar to the PHP manual, but how does that get accomplished with such an organic set of processes in place?
Further, Steven, I must concur with Ryan (rcross) on his point about your typical response mode. I've not been lurking around the community for long, and I have noticed the same behavior. Not that I am attacking you on any point, sir, merely that I have noted a rather elitist and pointedly snippy tone in many of your posts and replies, both here and abroad. You're obviously overworked, overtaxed, and tired of people whining about not getting the world for free while not contributing anything meaningful themselves. These concerns I can rightly understand. However, I certainly don't feel that I fit into that corner, as I have attempted to spark a discussion that may well lead to a better and brighter future. Yet your feedback in this thread amounted mostly to, "get off your ass and do something," with a healthy dose of, "do we have to spoon-feed you newbies or what?"
The reply to such tone is, in fact, yes. Yes, you must, absolutely, spoon feed every new member of the community exactly what was fed to you and every other contributing member in the hopes that they will become such contributors, as well. Indeed, now that we can all be considered contributing members, we must continue to foster the contributions of others in a spirit of good will, so that they will grow into us and do the same going forward. Some will contribute unknowingly by asking the most elementary questions about Drupal.org in the most moronic method possible. These folks will inadvertently demonstrate where the usability of the site is lacking, what might have been missed by the seasoned users, and what should probably be addressed more clearly elsewhere.
For example, there's a new post right now titled: "Submitting a module?" (misspelled) This person was interested enough in contributing to the community that he or she wrote a completely new module with a completely different set of functionalities than similar or identical modules already submitted. This person was also uncertain of how to submit the module for review and admission to the repository, even what the guidelines were for submission in the first place.
Is this an indicator that this user is a complete moron who can't read or didn't take the time to sufficiently look around?
It's possible.
It's equally possible that this person DID look around, poked through the site, read the documentation, and simply didn't see the information because it wasn't organized correctly.
Since this person is obviously bright enough to write a module for Drupal (something to which I have not yet aspired), I'd be inclined to assume the latter until proven otherwise. Therefore, I must draw the conclusion that although (nedjo) knew exactly where to look, maybe it's not as obvious to a new user where (or how) that information can be found. That's an organizational issue, not stupidity, which is irreversible.
So, please, let's keep this a discussion between rational individuals and assume that most everyone has at least given the whole site a once over, perhaps more than that. I know that I have, and I still haven't found everything that I've searched for... eg: How come I can't conduct a search for "project.module" in the Modules section and return any hits relevant to "project.module"?
And I'm not looking for an answer to that question nor a node location for any of the other answers I may be seeking, at least not in this post. I'm merely illustrating my point, that the organization of the doc pages and books needs to be addressed, discussed, and revised based upon that discussion. That's what a forum is for, after all, correct? Maybe, just maybe, some forum posters are contributors, too... Or are trying to be, at least. Discuss amongst yourselves...
You are reading to much into
You are reading to much into it. There is no 'tone' to my post, there is no 'elitist' mention. Do not try and read into my words that which is not there. I am not flowery. I try very hard to convey information and educate witout a lot of verbage. I will say that I was not spoon fed upon my arrival here and much information I looked for did not exist. So as I found stuff I wrote it down and contributed it. This allows those that come after me to pick things up easier and ask different questions. This is all I ask others to do. Being new, you are in the same position I was. Now is the time for you to write down solutions and add that which you found hard to the store of knowledge.
In general I try and answer the question asked. So many people new to software flat out do not know how to do basic research on any paltform much less Drupal. This is a common failing across the tech sector, not just Drupal. So I provide links to the handbook page when posible. Most obviously do not even bother to look at the handbook page and so when they ask 'what is a node', I answer with a link to the steps to get to the answers (Introduction to Drupal terminology). This is not because I think someone is dumb, it is because I think they don't know how and am spoon feeding them the steps so they learn how.
No, that's your words, your comptempt of me and my attempt to offer you the avenue of improving things. My words are How to contribute. How to make it better. How to get involved. At no point did I say anyone was lazy, at NO POINT DID I EVER EXPRESS CONTEMPT of newbies and I am insulted as hell that you claim I did.
I answer newbie questions all the time. I write handbook pages to help newbies. I BEG and PLEAD with people to HELP contribute pages that help newbies. Everytime someone starts one of these threads I try and get them involved in contributing to solve the issue they bring up. I know I am beating my head against the wall and that the vast majority of people that do this will not ever contribute. That's fine. If I get one person per thread I'll be happy.
Instead, you have chosen to take my efforts to get people involved in helping you engineer a solution as an attack. This is sad and not all that productive. As to improvements, you are speaking in generalities. Did you have a specific question?
As a point of information
This is an incredibly patronizing comment to leave at the end you know, like you are somehow 'above it all'. I am certain you didn't mean it like that, but there it is.
Look, you want to help, then please do. Get involved. We'll gladly discuss it. If needed, we'll make changes after the discussion. Making changes is not a problem, making changes without discussing them or understanding why some things are setup the way they are isn't useful. So, what don't you understand about the current organization and what do you specifically think needs to be done. Let's see if we can reach that understanding and go forward with improvements.
You mentioned wanting to spoon feed newbies... good. Let's discuss how to do this. What do you propose?
-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
Back to organization
Mild flame wars aside, if we get back to organization itself...
I think there may be a couple of different issues going on at once, here.
First, is the question of whether the drupal.org's handbooks are organized in such a way that they are user-friendly to all levels of users, from first-day newbies to veteran module writers and drupal power-contributors. I think the original poster and myself are saying that this may not be the case. However, I'm not quite sure (yet, though I've been thinking about it) just exactly what a better organizational scheme could (or perhaps I ought to say "should") be like. I'm still toying with it... though I will give a first guess below.
Perhaps my own personal experience will lend some light to the subject. I went through 3 stages. At first, as a "day 1 newbie", I had no trouble at all with the "basic install and use" type instructions. At this stage I'd have said the manuals were very well organized. Then, however, as I got into more advanced things, like trying to build my own PHP or HTML-based blocks using the block editor within drupal, or trying to customize my themes (rather than using ones someone else had designed), at this stage, I was no power-user, but I found the help files/guidelines a bit hard to use -- finding what I need necessitated sort of knowing where to look ahead of time, which was a bit difficult to know, given that I hadn't found it yet. It took a huge amount of poking around to find what I needed at this stage. Perhaps you could even say there was too much information, because lots of entries looked as though they were going to help, but ended up being way more in depth than I could understand, and than I needed. Simple step-by-step instructions on things like theming were (at the time, though this has somewhat changed since) lacking both in ease of being located, and just in general.
Another issue is the hierarchical/outline form of the book pages. You can only see (as far as I can tell), the next level of organization below the page you are on. There doesn't appear to be a "table of contents" function in books.module (or if there is I have yet to find it), where I can click on a book and get the whole, expanded, table of contents with all the child, grandchild, and great-grandchild pages listed. That means I have to keep working down and up, down and up, into the book sections till I find what I want... This can be a bit frustrating to the end user. If I don't know which section to start in, I could be barking up (or in this case down) the wrong tree for a long while.
Then I hit the 3rd stage, where I am now, which is that I finally 'grok' the way the help files/handbooks are organized and I can find my way around pretty well. But it took a while to get there.
I think this may be to some extent what the OP was talking about. It's true that some of the individual pages are not written in a way that is helpful to many new users, but also that the organization of the handbooks is not as inuitive to some as to others. As I say I changed over time -- the early/basic stuff I found to be intuitive, then as I got more advanced the later stuff was less intuitive, and now after using it a while it is more intuitive.
I have grappled with this on my own site. I thought myself that drupal was pretty easy to learn the basics of, but many of my users at the Roleplay Cafe -- who are used to more typical forum-centric sites -- have had difficulty. They found the whole system non-intuitive, until I finally wrote some very basic (to me, though I am not sure how well they work for the users) step-by-step tutorials with screenshots of what checkboxes to use, etc. For example, something simple like knowing when to include taxonomy terms (and which ones to include) seems to have escaped most people so far, despite weeks or even months of using the site (and despite me using them a lot so that it should serve as an example). So I wrote a tutorial on that just the other day.
One concept that has been used for 2 years at the forums for the game City of Heroes (which I play for fun) is that people submit guides regularly, and there's usually someone (the forum moderator or a designee of the moderator) who keeps an updated and detailed "Guide to Guides". Basically this is a post that explains what each guide does in a few sentences. Perhaps something like that would be useful here. There are 5 guide books with about 50 different sections to them listed in http://drupal.org/handbooks, and other than search and the brief titles of these sections, there's no way of knowing for sure where to look for what you want. I am sure the organization makes sense to the authors and site organizes, and by now it does to me -- but it may be this that is a bit confusing.
What if we had some sort of a "reverse lookup table" as it were.... A place where people could, instead of looking up the topic by title (which can be hard -- if the title doesn't match the question in your head you won't think to click the link and look in that section), we had a verbal description. Let me see if I can come up with an example:
If you are having trouble getting your site to work equally well with different browser platforms, check the chapter Troubleshoot your Theme.
If you are looking for information on how to configure your drupal site so that blocks, user profile preferences, and other such things are to your liking, try the Basic site configuration chapter.
... and so on.
Yes, I know, these things may seem like they should be obvious, but a reverse-lookup guide (not sure if that's the right term but I'll use it for ease) might help people. Then you could have a link... "Having trouble finding what you want in the handbooks? Try this guide to the guides!" As I say they do this on the COH forum, and people like it.
Anyway... just a thought.
Do others think this would be useful? If so I just might try tackling it and submit it for peer review when I get it done. (Though since it's a much smaller under-taking, I may test this system out on my own website first and get back to you with the results.)
Also, I think if book.module would have a feature where you could ask it to print the whole list of all the books, their sections, subsections, child pages, grandchild pages etc -- just the titles of these -- in outline form, on a single page (with links to each node of course) this would also be a huge potential help. I realize this feature may exist and I may just not have found it yet so if so please enlighten me... I think it'd be dead useful.
SV
What if we had
someone who is not wishing and thinking in kilobytes but actually does it?
And folks, what else do you expect? If you want to do it, do it. If you need a tool to make it happen, shout! I tell you noone who want to be a ditchdigger here but needed a good shovel was denied. In other words, Dries often told us that he will give any resource needed to make things better.
--
The news is Now Public | Drupal development: making the world better, one patch at a time.
--
Drupal development: making the world better, one patch at a time. | A bedroom without a teddy is like a face without a smile.
Several Points
Ok, first point - I completely understand the issue - "if you want it, then do it" or "if you don't like it, change it" and all the variations. However, this discussion *IS* doing it. It seems obvious (to me at least) that the people that have responded to this thread so far are actually trying to make contributions, and simply by having this discussion we are contributing. Secondly, by discussing problems with the documentation we're trying to fix them not just complain and hope someone else does it for us. So, with those two points in mind lets keep things constructive.
Now, onto other points -
I'm sure some people will disagree with me here, but I feel there are some barriers to entry here. The fact that I can't edit a page makes its much more difficult to make changes or contribute. I know that I can add a child page, or I can add a comment - and if a change or write up is significant I will try to do that. But minor changes, tweaks, updates, rewording, spelling corrections, etc are basically prohibited. A good example is that book page regarding the table of contents. Personally I read that page and see 2 different issues discussed which i feel should be separated in order to clarify - but I can't make that modification. You'll also notice that the page is marked with 4.6 (great!) and someone has even made comments about how to change it to work with 4.5 (no mark) - however, when i'm doing work with 4.7 I only want to see documentation for the version I'm using (and if i can't find it then i'll go back to find something to port forward). At the same point, especially with the new forms api and other core changes, if i were to make changes to that page to apply to a different version then currently it is reflected in all versions. What "should" happen is if I make changes to a page, and it stops being 100% applicable to an older version, then a new page should be created.
To hammer the point a little farther, someone should've been able to edit that book page to incorporate the 4.5 changes, change the page to only refer to 4.5 and then save a new copy. In the same regard, if I found that those instruction still hold true for 4.7, I should be able to make that addition. Also, at this moment I don't see any clear way of looking at *just* 4.7 documentation or just 4.5 - there is no handbook for 4.7. I think this is part of the reason why sometimes there is too much information - we're looking at more than we really need to.
This barrier contributes to a couple of issues with the documentation. The fact that it is not easy to make changes leaves alot of people feeling like either its too much work or that their change isn't significant enough to make the effort. Also, the other poster mentioned that titles aren't quite as descriptive as necessary to find what you want - this could easily be an example of a minor change that isn't easily rectified.
Another feature that I think should be available in the handbooks - especially in an electronic form- is the idea of cross-links and related information. Again, that book page is a good example. It definitely related to the book module, and should be classified as such, but the code fragment is also definitely a PHP Snippet or Tip/Trick that should be classified under that area as well. Also, the book module related to structured navigation - but there is no "related pages/topics" to help direct people to the other pages that might help them. A similiar idea is "related forum topics" to help tie the history of things together. A good example of that is this node http://drupal.org/node/31896 regarding a site configuration. This is something that should *definitely* be in the handbook, however there are lots of different solutions that people suggest and i've see posters send people to this post several times plus it hasn't been closed to comments so every so often a new solution will be posted or critiques added. I think it would make sense to create a page in the hand book that says. "Creating a coporate brochure site - read this thread for the details" at least it helps people find this classic/key thread.
As I've mentioned in the earlier post, I wouldn't be opposed to implementing a wiki or something of that nature to help deal with the documentation. I'm sure there will probably be some comments about eating our own dogfood, but i'm also of the nature to use the right tool for the job (and maybe this reflects some of drupals weak points).
Another idea that I probably didn't make clear was the idea of flagging forum posts as "solved" problems. A good example is a post that I made recently http://drupal.org/node/62582 where I started with an issue and eventually got it resolved. I wanted to rename the title of my post to denote that by adding "[Solved]" to the front, but I couldn't do that - a moderator needed to do that. Also, I could've easily left that post as it was but I decided to take the time to do a full write up and contribute it to the handbook. Of course this would be the ideal situation, but sometimes a small "solved" issue might not warrant a full write up. But this type of "flag" or procedure could easily create fuel for book contributers to write and it would also make searching for solutions that much easier. Since it never helps to find a post that sounds like the exact problem you're facing only to find that the poster wasn't able to get help either.
I'm sure there are some other ways to improve the documentation work flow (I also like the idea of reverse look up or topic based links, maybe even a "understanding the documentation" page) but hopefully we can discuss these ideas first and see what other ideas people can come up with.
--Ryan
--Ryan
Ryan Cross
James Cross Construction Services
Project Management Software
I suppose I see the value in discussing
I understand that but I suppose I see the value in discussing this rather than "just doing it."
From where I sit as an end-user, I think in large part the lack of organization is due exactly to this -- people just randomly "do it" without any real organization before the fact. It's fine to want people to contribute (and I would like to contribute) but I never do anything without a plan, and I think there is some value in discussing what should be done.
We have identified a problem -- organizational difficulty, combined with (or perhaps causing) difficulty of use for newbies. If we want to actually correct the problem rather than just randomly posting pages that we think will correct the problem, we need to figure out exactly why the current system is causing these issues, and then, what the best course of action is to correct these issues.
To do that, we need a discussion, not simple unilateral (if well-intentioned) action. The unilateral "just do it" model gives the appearance of corrective action (new pages are posted, 'something got done') without any actual correction necessarily taking place. I think the discussion of what the problems are and some conversations about the best solutions to rememdy the problems are a necessary first step, and a thread like this one (and any sequels it may spawn) is a good start. The whole point of having a community work on things like this is so that more heads than one can attack the problem. The whole reason there is an organizational issue is that individuals have worked largely in isolation on whatever they thought would be a good idea, with no regard to how it all "hangs together" as a whole. The only way to correct this is with discussion and planning. This cannot be achieved with "just do it" as the M.O.
As an example, I posted a thought about having a "COH" style "guide to the guides" (or perhaps to use drupal lingo, "handbook of handbooks")... I am not 100% sold that this is going to do enough good to be worth my time (or someone else's) to work on, so I asked if anyone had any opinions. Perhaps I should make a new thread about it... but the point is this -- I'm not convinced this is the right fix, but I think it's possible, and I'd like to get some opinions on the matter. And that should be what a forum is all about, no?
I don't necessarily WANT to write a handbook of handbooks. I might do it, if enough people agreed with me that they thought it was a good idea. But I don't have a large # of hours to kill in writing a handbook that nobody but me will find useful, so if that's the consensus, I'd rather do something that's more worthwhile with my time.
As I say... I value discussion and I think it is worthwhile to ask for feedback before undertaking something like this. There may be much better (and less labor intensive, always a plus) ways to solve this problem.
SV
I agree
Hey Steve,
I think we're on the same page here. I would also point out that if you spent the time to make a "handbook of handbooks" that only you found useful, it probably wouldn't be very useful to you after you wrote =) Maybe we need to take this discussion into a different thread or somehow put it in front of people that are more intune with the point of this discussion. I don't know where that would be though.
--Ryan
--Ryan
Ryan Cross
James Cross Construction Services
Project Management Software
I am the person you should
I am the person you should be discussing these desires with. I am the current handbook coordinator/lead. I have this horible feeling that no one is reading what I am typing. There have been several suggestions already on how to contribute and I am waiting for concrete suggestions beyond, it should be different. They seem to be ignored.
-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
Summary of my suggestions
My posts were long so I will distill and summarize. My 2 suggestions for making the handbooks more useful and perhaps appear more organized to the unfamiliar end user are this:
1. Perhaps have someone (I might be willing to try, but you need to realize I am no expert on about 3/5 of the entries) write a "guide to the handbook" that basically is like a reverse lookup table. I.e. "If you are looking for advice on how to do X, see entry Y." I know the titles may seem like they do this, but often the titles you are 3-4 levels deep in the hierarchy and you can't see them from the top entry, which leads me to...
2. Have a fully expanded (with all links and sub-pages) Table of Contents for the books. This will probably involve a complex SQL query that is far beyond my meager coding abilities.
Those are 2 suggestions beyond "it should be different." Perhaps they're not going to be any better. I'd like to see what other people think. I might be willing to tackle (or help tackle) #1, if enough people think it'll be useful to the general public. But I'd rather not waste my time if most folks think it won't be any more helpful than what we have now. I readily admit what is useful to me may not be generally of use to most people -- my brain is a bit strange. ;)
My Summary
Hey Steven,
I'm glad you're interested in this conversation, it just seemed that it was dwindling into "lets make some changes" vs "try contributing in the existing framework". Sorry if I offended you, I would definitely want to speaking with the current lead - it will definitely make sure any suggestions are actually read and heard. Anyways, following on the other post here is my summary of suggestions beyond what you have given us.
1) Address the barrier to entry by opening up the handbook to everyone for editing - or at least more parts of it. There may be ways of correcting minor issues in the current system, but its not easy or intuitive enough for most people. I know that i would never really think to submit an issue request for documentation unless there was something not loading or bad css or something.
2) This might require code changes to the book module, or changing how we do things, but I think there should be an easy way to seperate documentation by version. I only want to look at the handbook for 4.7 (and if i'm working on a legacy site, i want to look at the 4.6 handbook). Tagging is a start, but definitely far from a real solution
3) Similiar to taxonomy having related terms, i think book pages should have related topics/pages. I also think there should be more efforts to cross-reference posts within the handbooks.
4) As a general suggestion, I think we need to find a way to distill more knowledge out of the forums and into the handbooks. One suggestion is to be able to mark a post as "solved" once a solution has been found to work (this should probably include closing the topic to further comments). Another suggestion is to commonly referred topic threads, and put a link to them in the appropriate handbook. A third suggestion is to create a pool/que of "solutions"/closed forum topics that could be turned into book pages, but haven't been "cleaned up".
--Ryan
--Ryan
Ryan Cross
James Cross Construction Services
Project Management Software
Book navigation - table of contents
A quick search turned up this snippet (for 4.6):
http://drupal.org/node/44648
Could something like this, set to show the full (or nearly full) depth, be added as the first child page for every handbook?
---
Work: BioRAFT
That snippet
That snippet looks like it might be what I'm talking about. I'm not much of a coder though (alas). I know CSS somewhat, but not really PHP or SQL.
Cut the fat. Skim milk is better for you.
I skimmed the original post and spent even less time reading the responses here. The key to better organization is presenting info concisely. If you need further discussion on this topic, branch it out to other topics. This lengthy thread is an excellent example of losing organization of content.
Please do not quote me or post that you agree with me or else you will add more fluff to this thread. :)