Posted by José San Martin@ on March 28, 2008 at 1:34pm
I've been discussing with wundo a few ideas we have about a "Drupal knowledge base" and I think this could be included in the coming Drupal.org redesign.
This Drupal knowledge base would be a place for keeping very consistent and comprehensive documentation for users and developers and a place to gather useful information that is currently dispersed on the web.
This knowledge base, as planned, would include these elements:
- Handbooks. Very concise and precise documentation. A clean-up could be done on current documentation to reduce to essential. At the same time we would expand the handbooks to cover more and more topics. The unessential information would be moved to other parts of the knowledge base.
- Tutorials. An easy way for people to create step-by-step tutorials full of screenshots.
- Tips and Tricks. Short nodes would store short tips and tricks to do simple or complex things... From taxonomy theming to OG tweaking.
- Screencast. A screencast repository, probably with videos hosted at blip.tv or at another similar service.
- A comprehensive and specific taxonomy system, including vocabularies: for Drupal version, for user level (beginner, intermediate, advanced user, module developer, Drupal hacker, core developer, very very very advanced), for topic (site building, configuration, contributed modules, etc) and free tags.
- Drigg. All tips and tricks published in the blogs should be gathered and classified at Drupal knowledge base, in a Digg-like style. And when I mean "all" I mean "all": we should digg all blogs registered in Drupal Planet and look for interesting things.
- Drigg. Content karma (voting) could also be implemented to select the best tutorials/tips and tricks/screencasts in town and promoting weekly a few to the front page. Perhaps user karma could also be enabled to encourage community contribution.
- Heavy investiment on Internationalization. A true Drupal knowledge base should allow non-English speaker have their content in their languages too. Just a few national Drupal communities have sites that are good enough to host comprehensive documentation. We should be able to translate the handbooks, tips, screenshots and everything else.
Build a website with these feature is not a complex task. The necessary documentation work is not simple, though and require a lot of work, but on the other hand it really worth it and would represent a significant step in Drupal world domination.
Comments
docs.drupal.org
This sounds exactly like the sort of thing that'll be possible on docs.drupal.org when/if it exists. The D6 book module will make reorganising what's there a lot easier. Node types for different kinds of documentation sounds good as well (as does some/more voting/tagging/versioning).
Probably the first step would be moving the existing handbook to the subdomain (which'd ought to be quite easy to do and could happen fairly quickly) - then it needs a commitment from people to both work on introducing that functionality and populating it. Most of the actual work could happen incrementally though.
Yes, docs.drupal.org
Yes, I did intended to write that it should go to docs.drupal.org, but somehow I missed to write it down.
So we might have:
- Handbook as books (a handbook, a book)
- Tutorials as books (a tutorial, a book)
As I said before, building this website structure is relatively easy with Drupal and no coding would be required (except for the upgrade of Drigg). Rewriting the handbooks, though, is a more complex task, surely. It would be nice to make the handbooks lighter, moving stuff to the Tutorials and Tips and tricks sections.
Me and Fabiano (wundo) would be glad to build the structure of docs.drupal.org and help with documentation.
José San Martin
Got some things to emphasize...
Got some things to emphasize...
*Love the idea of screencasts, I think we need them and they are sorely lacking at the moment. We need LOTS OF THEM for almost anything you can think of. Users (all of us included) are very visual and we can throw 200 hours of documentation out there about how to create a new drupal space and not have the same impact as a 5 minute screencasts about the topic.
*Internationalization - can't we use the google translation api to at least help out with this? I know it's fairly new and I haven't used it yet but we could automatically run it on a page to match the language their browser is in. Or allow them to select what language they use in the user profile for d.o and then translate everything if it's currently available. Just a thought to jump start that process though I do agree it'll be very important as well.
Few things I also think would be good to add to this:
* A thesaurus / encyclopedia / dictionary approach to drupal terms. Using your ridged taxonomy of user level / topic we could provide multiple definitions for common (to us at least) drupal terms and concepts. Maybe some kind of inline definition system where if it knows it's a term it auto highlites it as a term you can click on to get more info. Kind of like a wikipedia for drupal...a...drupal-pedia :P
*Probably similar to your drigg blog idea but a block or list of related topics or something like amazon's 'users who bought this bought' or 'looked at' so that users could see what other related topics people are looking into.
*Multiple paths in and out of critical content - big questions like 'how do I install a new module' and others that, if unanswered quickly, could cause people to become fatigued with the learning curve of drupal and cause them to leave the community before they join are critical. Lowering the cost of entry in as many ways as possible would be huge. A few days ago I posted to CVS for the first time and it took me more then i'd like to share hours in order to get it all figured out the first time just because I was missing the one or two nodes of documentation that I should have been looking for.
Ex Uno Plures
http://elmsln.org/
http://btopro.com/
http://drupal.psu.edu/
And I got some to reply...
Me too. Blip.tv integration, I think, is the way to go.
Never! Please, never ever! Ever! :-) Automatic translations doesn't just suck, they are completely incomprehensible. By incomprehensible I mean that one can't even guess what the automatically translated text means.
By internationalization I mean: allow non-English national documentation teams translate the English stuff to their own language. And, why not?, produce documentation in their one language, too, and translate it to English later.
A good idea, but not similar to the drigg idea. We could have them both. (remember that appart the voting thing, drigg is also important to gather tips and tricks from blogs around there)
The encyclopedia approach is interesting, but doesn't it have the same functionality the handbooks have?
Maybe we could just add a glossary functionality, linking to Handbooks et al.
Yah, that's what glossary would be.
Yes, a FAQ would be great, too. Answers doesn't need to be long, just objective and linking to further reading.
Really not into / up on dig
Really not into / up on dig / drigg so I wasn't sure if they were similar. Glossary is the word I've been reaching for and haven't been able to grasp for the last week that i've been on about this idea. Yes, a glossary is what I meant by dictionary and all the others. I like that in the APIs there's that auto complete field and having something like that for a glossary search would be useful too.
Ex Uno Plures
http://elmsln.org/
http://btopro.com/
http://drupal.psu.edu/
...
I would like to point out that tutorials, videos, tips and how to article already exist in the current handbooks and that people can already contribute. At this time drupal.org is English as the primary language and I do not see this changing in the near future due to resource constraints, etc. Perhaps over time yes.
While digg is an interesting site for transitory news data, I am not sure what the long term value of doing such on drupal.org itself would bring us. The additional maintenance overhead and the transitory nature of the content would render such things of very limited value time wise regarding relevancy in documentation. Perhaps I am using digg in a different way though. I'd need some seriously convincing use cases though.
I am also not sold on docs.drupal.org. We in general do not use abbreviation in drupal code, so I am unsure of the acceptability of using it for domain URLs. Various other open source projects use everything from support, to help, to nothing so there isn't really a trend there to help identify either. Drupal code doesn't abbreviate because it's hard enough for people using English as a second language as it is to then toss in abbreviations as well.
Are you sold on a separate
Are you sold on a separate site for help that is operated by a "docs" team? thats what we intend. The actual domain we choose is less important.
.....
I know that, and that's exactly why I want them separated in docs.drupal.org. The handbooks are a little bigger than they should be. By creating a specific place for tutorial and another for tips, not only we can enhance search systems, but also make Handbooks lighter and easier to use.
That's another reason for docs.drupal.org. I know drupal.org can't get fully translated. (for instance, why would we translate issue tracking? or post at forums?) If we could, though, create a good space for Drupal documentation, a separated website at docs.drupal.org, we could enjoy full internationalization features. Just a few Drupal national communities have decent documentation projects (not the case of Brazil, for instance) and we do need at least part of the translations in languages other than English, because there are many people out there who need it in their languages.
The digg would gather specifically tips and tricks that bloggers post in their blogs. Go and see Drupal Planet. There are many people telling how they build their stuff. We need to archive this knowledge somewhere. (that's the Knowledge Base thing) We need to digg stuff from the blogs and make it easier findable.
Disagree. The digged tips are most of the time relevant for a specific version of Drupal. Aren't the handbooks the same thing?
Moreover, there are the taxonomies. When we digg a blog post, we will always set a taxonomy indicating the Drupal version that are compatible with that specific tip. When they render obsolete (and they will), we just forgot them. We don't need to update them (although we will be able to, because people can comment on content). We don't need to update them because they won't be appearing in the search results. There's no maintainance needed, then.
What do you suggest? support.drupal.org, documentation.drupal.org, help.drupal.org, kb.drupal.org, knowledge.drupal.org?
By the way, I don't like help.drupal.org, because it will be no place for people saying "help me!". The forum is. Non-English communities forums are. The documentation website is intended for documentation, not support or help. In other words, people "read" in Drupal Knowledge Base, people don't "ask" at docs.drupal; they'll ask somewhere else.
Disagree. As a non-native speaker, I can assure you that DOCS is pretty much easier than support (which could be also written as suport) or documentation, or knowledge (people who can't read English can't even guess how to spell knowledge) or anything longer than four letters.
Sorry for the long response
I see this as something similar to the work already going on with the Getting Started guides that are concise, "official" and in PDF. There was discussion of a similar process being applied to other important "core" information in the handbooks (like the theme guide, dev guide, etc.) I think this is generally a good direction for us to keep going. These would also be the first things to be translated once we can come up with a good way for that to happen (they are in docbook format - not regular handbook pages.)
We have tutorials, howto and snippets sections in the handbook and it isn't so much a matter so much of "an easy way for people to create" them, our bigger issue is how to organize the stuff folks create. This has been acknowledged to be a "bucket of stuff" right now that needs some real thought to sort out in a more useful way.
Yep, again, we have this and as the other video post discusses we need to work on two factors to improve this area: 1) better ways of "getting" them, e.g. aggregation and 2) how to not only organize them in a video section, but integrate/link them from within the written documentation. I like blip.tv myself but that doesn't mean we're going to get everyone to use it either. We need to be able to have videos from many sources and d.o itself doesn't need to take a stance on where they are hosted. At the end of the day any outside source is a weak link for d.o and with videos we just have to deal with that fact since we aren't going to start hosting all vids ourselves on d.o servers.
Yep, I agree that better taxonomy is probably one of the first things to hammer out.
This I am not so hot about but I do get the underlying need being identified - getting useful info from the blogosphere into the handbooks. Maybe that's because I am a not a Digg user. I'm also not at all familiar with the process or modules involved so I've got just plain ignorance in terms of how this would work. How do we "limit" which blogs can be dugg? When you say "we" digg do you mean all registered users? How do we make sure the stuff that is dugg is actually a tip/trick or even Drupal related? (Insert other ignorant moderation-type questions here.)
I'm generally not a fan of "karma" systems. They just get weird, especially in open source where real community karma is measured in many, many ways. In terms of voting for things, that could mean so many things to so many people that it just doesn't sound like fun to me. The "best" tutorial is the one that fixes your need. Everyone's needs are different so aside from ones that plain don't work, I don't see this as necessary.
Yes, I think this would be a very cool thing to offer (and yes, I am thinking in terms or core and i18n, not an outside service.) I also think it will require some serious thought on the best way to allow people to contribute translated documentation that works.
Overall I think the main thing and the whole point of the d.o redesign (including documentation) is to figure out how to better organize the content we have. I'm not averse to cool new things at all (and really want some) but I think we need to focus on how to best organize/rework what we have in a way that eases use, brings clarity and helps maintenance first and then look at adding in other features (like your Drigg idea.) We don't have to do the whole shot now and we have a mountain of junk to do already. As you said, building the site features out isn't the hard part. The seriously hard work is figuring out what to do with our content and until that gets nailed down, I'm not up for adding more moving pieces to the dynamic. We can always add features later. That said, ideas are great to move around and discuss so I'm not trying to shoot anything down. I just want to keep focused on the tedious, hard, nasty, unfun stuff that really is at the heart of what needs to be done.
Lullabot loves you
Learn Drupal online at Drupalize.me
I see this as something
Great! I did know that the Getting Started existed, but I wasn't aware of its progress.... We could integrate them to the regular handbooks later in docs.drupal.org, couldn't we?
We do need to move tutorials and tips out of the handbooks, don't we?
Agreed.
Yes, and they're great. I just think we could have more tutorials, how-tos, tips and snippets, and keep them more organized, if we strip them from the handbooks and give them a new home.
No, it's not, you're right. I was just thinking on "an easy way" to upload images (screenshots) to the tutorials.
By the way, tutorials should be books, right?
Me neither. :-) But anyway, I don't see better way to gather the knowledge from the blogs? Asking bloggers to write in the docs and not in their own blogs is unthinkable.
I think we have to limit which blogs, but which content. Even a great Drupal tip provider (uhm, Lullablog, for instance) publishes stuff that are not Drupal tips at all. (for instance, an anouncement) So, it's up to the users digg what they find convinient knowledge. And if someone digg something that's not a tip, we may just delete it, in the very way Wikipedia deletes its dumb articles.
Anyway, limiting would be easy: just check if the blog is in Drupal Planet.
We could separate docs in two sections:
- a moderated section, the Handbooks and the Getting Started, editable by only a selected few.
- and a wiki section, for tutorials, screencasts, tips, diggs, etc. We would work in the very wiki way: trusting our users in first place, deleting non-sense posts and banning abusers. The Drupal community is mature enough to work in this way.
Well, it's true, you're right. So: dropping Karma from this proposal!
I do agree with you in that. So could we have a road map like this?
José San Martin
Chuva Inc | Southern Drupal
exception
I realize you are not a member of the documentation team. I am not sure why you have not followed the process and requested this while you are proposing a new system but that's all right. I do want to clarify something though...
The existing handbooks already work in this manner. It has worked in this way for several years now. Please do consider joining so you can see what is already being done. There are over 250 people who have done this.
No intended arrivism
Sorry, I didn't mean to be a newcomer-who-wants-to-change-it-all. (an arriviste).
All I want is bring some discussion on docs.drupal.org, since we're all discussing here in this group ways to redesign drupal.org.
So please understand what I said as:
What I am really concerned in this discussion is find solutions to:
How can we reach these goals?
Regards,
José San Martin
this sounds familiar
So far nobody who has posted in this thread has added anything to a similar discussion that's taking place in the Wiki group. I'm a little concerned that the overall discussion is getting fragmented, but I'm certainly happy to see people come from different directions and arrive at similar ideas.
Either way, I suggest incorporating the ideas that have already been discussed at http://groups.drupal.org/node/7837
Oy
Well probably because we are not following that group and this is a discussion that should have been brought into the redesign thread or at least the docs mailing list way before now.
I've not got the time to process that thread nor respond right now but it should probably be brought into the greater redesign discussion before getting too far off on its own (which in a cursory view looks like it is.)
Lullabot loves you
Learn Drupal online at Drupalize.me
Yeah I'd never seen that
Yeah I'd never seen that discussion either. The redesign group has been around a lot longer than that post though :P
I agree with a lot of what's already been said. Once we have docs.drupal.org (and for that matter D6 book module) it'll be a lot easier to split stuff out of the handbook - like getting started already has been. So there's a minimum level of documentation that's upgraded (and potentially translated) each release, along with easier organisation (and yeah, better taxonomy would make a massive difference by itself!).
Once that's done, then making everything else look more wiki-like is trivial to do - as would different permission sets compared to 'core' documentation. The issue at the moment isn't that we don't have a wiki, it's that we have a massive, massive wiki-like thing which has a tendency to get bigger and more unwieldy the more open it is (because people add first, edit second - because it's hard to find stuff) rather than refined, which is why there's some controls on who can edit it. So overall I agree with add1sun that the split (both from d.o to a subdomain, and within the subdomain to the different bits outlined above) and reorganisation needs to happen first, then opening it up once it's clear what goes where. If we open up, then split and reorganise, the last bit will never happen because it'll just be too much firefighting.
With the drigg thing - I already want to see planet aggregated into my.drupal.org via feed api - which'd allow us to split it up into various subcategories easily. Adding some kind of content recommendation logic into my.drupal.org is going to become necessary as *.drupal.org keeps growing exponentially - so if we have that logic in general (user relationships, bookmarks, taxonomy, pivots, memetracker?) then it ought to be possible to feed it back into docs.drupal.org from there. So we have a central place which aggregates, sorts, filters and recommends *.d.o and planet content - both individually and at an aggregate level, then views turns that back into a few centralised feeds which populate areas on the other subdomains.
suggestion: "Join Drupal Right Away!"
One other thing that might be useful in the Drupal Knowledge Base would be an eye-grabbing, top-level link to a section on all the ways users can "Join Our Community Right Away!", so that newcomers could immediately connect to the Drupal community with their IRC client, RSS Reader, mail reader, bookmarks manager, and other knowledge gathering/exchanging tools. This might boost newcomers up Drupal's learning curve (and help eliminate drop-out) by providing them with the means to fully-participate in the community right from the start.
What constitutes "eye-grabbing" can be left to the web designers. :)
In the meantime, a preliminary outline of such a section can be found at http://drupal.org/node/233601
Once you open the outline, see:
Drupal Project - Knowledge GUI > Contribute to the Drupal Project > Join Our Community
Below is a partially-expanded version of that outline:
Welcome to the Drupal Community
* Hitchhiker's guide to the Drupal community
* HOWTO: Enact change within the Drupal community
* Tips for posting to the Drupal forums
Security Announcements
* RSS
News and Announcements
Newsletter
RSS feeds
* Drupal.org RSS feeds
* Lullabot RSS feeds
* groups.drupal.org RSS feed
Mailing Lists
* Join
* Archives
Tag Aggregators
* del.icio.us
* Flickr
* Technorati
Web Watch
* Planet Drupal
* Drupal talk
* Drupal Association blogs page
Forums
* General
* Support
IRC Channels
* How to effectively use IRC
* #drupal
* #drupal-dev
* #drupal-support
* #drupal-themes
* #drupal-dojo
* #drupal-consultants
* #drupal-ecommerce
* #ubercart
* #drupal-docs
groups.drupal.org
* Local community groups
* groups.drupal.org RSS feed
* Events calendar
* iCal Feed
Conferences
* Drupalcon Barcelona 2007
* Drupalcon Boston 2008
* Videos
* audio
association.drupal.org
Professional
* Hosting
* Services
* Hiring a Drupal site-developer
Drupal.org FAQ
* Theme and modules on Drupal.org
* About Drupal documentation
* Drupal.org RSS feeds
* Advertising on Drupal.org Why? How? Policies
* Drupal.org site maintainers
Bug Reports
Feature Requests
Project Issues
Also see the docs team work
I agree that funneling folks into the community paths is pretty important. There has been a lot of work going on to create a new section of the handbook that is dedicated getting involved in the community. An outline and summary of an IRC meeting is here (http://lists.drupal.org/pipermail/documentation/2008-March/005924.html) and there are further discussions that happened at a subsequent meeting (http://lists.drupal.org/pipermail/documentation/2008-March/005943.html).
The basic idea is to incorporate information on how to get help with the how to contribute information, make it clear to folks that getting involved will help them as much as it helps the project and help walk them through what that means and how to do it.
Lullabot loves you
Learn Drupal online at Drupalize.me
Some hands..
We do drupal development from india and we have literally revamped our small team to have new 3 freshers (out of college) who are basically drupal virgins. I strongly believe to start with a system like drupal, one needs to associate with the documentation team as one search a lot of basic information on drupal in form of screencasts, code snippets and text to get them going. We also strongly believe in giving back to the community and hence have been thinking a lot about the culture where we can spend a portion of the day learning and contributing back. I am forwarding this node to my employer, I will love to get new guys to actively work with documentation. If there is a consensus on how the structure and workflow will be, it will be great to get guys going :)
One needs to strongly take it as part of work to contribute back, without which not much success is possible in personal skill development.. Will be waiting to see something getting concrete ..
Dipen Chaudhary
http://dipenchaudhary.com
http://playdrupal.com (under construction)
Dipen Chaudhary
Founder, QED42 http://www.qed42.com Drupal development
What Drupalist and Newcomer need
Hi all just joined in this group. Let me share some simple considerations about the mission here:
From the point of you of a real "normal" Drupal user, that means:
So say that i consider the Idea of doc.drupal.org as the best one:
About the review of all existent documantation on Drupal.org it can be done. We know that there
exist a potential of about 30.000 members on Drupal.org (please corect me if it's more)
The redisign og Drupal.org should take in consideration that the community will grow and grow and
foremost a lot of not native english speaker will come and want to finnd a really good way to orient
them self in using all the facilities provided to Drupal.org members.
I hope this was usefull to know.
Thank you for your attention.
Cheers
Cheers
Wolfflow
They need some hands..
Is anyone answering to the Mediawiki API? With Queries? Analysis, Building and Publishing?