In the not too distant future - perhaps soon after D7 work is finished - the Drupal handbooks will move to their own site within Drupal.org and hopefully the doc folks will then have much more control over their tools and templates. While it's very exciting to think that we'll finally be able to address some of our challenges - just adding Views would be amazing - I've been thinking that there's an opportunity here to do something that is WAY more awesome. Something that could return huge dividends to the Drupal docs.
What I'm thinking is that we could do more than just solve our own problem, we could use this opportunity to put together the foundation of a true technical communication CMS and release it into the wild. Perhaps even someday have an installation profile that delivers a complete technical communication CMS that anyone can pick up and run with.
The big potential payoff for Drupal docs is that by sharing our docs solution with the world we will hopefully get uptake from all manner of commercial and open source doc teams and that they will, in turn, have a vested interested in making the Drupal docs platform even more awesome by giving back ideas and code.
Some of the pieces (eg taxonomy and user access) are already baked into core and some can be added through standard modules (eg. views). But there are other pieces of a really awesome techcomm CMS which, as far as I know, are not currently available in Drupal or would require a lot of customization. Some things may have to be built from scratch. And it would be nice to have a really well integrated interface that ties everything together.
Here's a rough idea of what this beast might look like:
IMPORT TOOL - Ability to import XML-based content in DITA, DocBook, or custom formats. Able to monitor file folders or external databases/repositories for changed content and synch automatically or on demand.
ADMIN INTERFACE - Manage workflow, schema, taxonomy, GUIDs etc.
AUTHORING TOOL - WYSIWYG interface for creating and editing schema-compliant content. The writer can easily apply tags to content (but only the permitted tags for a given context!). The author can be given suggestions and prompts. There is a mechanism for conditional text (i.e. the writer can tag text and images so that different versions can appear in different publications). All this would require a lot of JQuery love to be usable.
PUBLISHING/EXPORT TOOL - Provides drag-and-drop interface for organizing content into single sourced publications (i.e. the same chunk can appear in many places). The publications can be web-based, PDF, XML, online Help etc. Different versions can be built using tags and conditional text.
Now I'm not saying that we should necessarily build any or all of this. Some of those features might never be useful for the Drupal handbooks. But I'd like to plant this idea that there might be value in thinking of the new Drupal docs site as the first step in creating a truly awesome platform for ANY kind of technical communication, one that will hopefully grow to become a project distinct from the Drupal documentation and with a community that is using it to manage technical communication for all kinds of products and projects.
What do you think?
Comments
Other features around outlines, lists, indexes, etc.
Some other features to think of revolve around being able to find, bookmark, and group pages. Just some random thoughts:
Have a particular topic page appear in multiple "book outline" types of things -- so that I could perhaps make a "Complete guide to building an xyz site" outline, by pulling together existing topic pages that already exist into an outline. Empower users to make these outlines, kind of like how amazon.com users can publish "lists". And when I visit a particular page, it could show me the default outline (site-wide one), but maybe also point me to other peoples' outlines, and let me switch to that one instead of the site-wide provide outline? Maybe that is some of what you're talking about in the Publishing section above?
Ability to bookmark pages or tag them in some way. E.g. I might want to make a "to look at later" list, and a "daily reference" list, just for myself. And maybe other users would want to see these lists too? Again, when I go to amazon.com and find a book, it tells me which user-created lists it appears on. Similarly, maybe when I go to a topic page, it could point me to other users' lists that this page appears on.
Indexing features -- maybe when you are creating or editing content, you could provide some keywords for indexing, that would be an aid to searching? Could prompt for existing indexing keywords that appear on the page, as suggestions, and maybe have a "other pages using this keywords also had the following keywords" suggestion area?
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
I think this is worth getting
I think this is worth getting excited about.
Main thing I'd recommend is a closer connection between issues and documents. This is sort of like how in wikipedia, the discussion pages are associated with the content. Also a workflow that makes it easier for people to just jump right in and make a quick change, but that allows for some control.
I thought these comments from above were particularly interesting:
Lee wrote:
jhodgdon wrote:
This is basically single sourcing, being able to generate documents with somewhat different purposes from a "single source." Something like this could generate a manual for a particular Drupal installation profile and only the places where they differed from core would change. So perhaps maybe just the screenshots would change, but very little of the language would be different. But then it would also be able to produce the document in different formats such as PDF, HTML, XML-DITA, odf, and this way companies could export a manual and do what they want with it in their own tools.
Lee Hunter's summary is something that comes from the perspective of technical writers, where the only free tool (that I know of anyway) for enterprise single sourcing is the DITA toolkit... which if I remember correctly requires writing scripts for Apache ANT (actually... I guess LATEX also does conditional formatting doesn't it?). A more usable, and still open source, interface for this, or an alternative to this tool would be a worthy project indeed.
This is something that technical writers would love, it might win some new fans of Drupal, and I'd definitely help out. It sounds like a big project though, so in that case I'm not sure if full DITA and multiple output formats is the place to start.
But perhaps this module for generating a custom manual, or as Jhodgden put it allowing for "...a particular topic page appear in multiple "book outline" types of things," which is the first half of single sourcing. i think this is something that we could have ready from the get-go, and that I think the success of such a module would benefit from an understanding of the needs of technical writers. It might simply be something that uses views, but with a special interface.
A little history
I first became seriously interested in content management systems about nine years ago when I was working as a technical editor in a large-ish documentation team (about 40 people). My boss had asked me to investigate whether a CMS would help address our many process and tool-related problems. We were mostly authoring in Word 95 (!?!) with Microsoft Visual SourceSafe as a repository and a bunch of other disconnected tools like spreadsheets, MS Project, email etc etc to manage all the deliverables and processes. The idea of implementing a complete CMS was tremendously exciting but at that time, there were very few available products that targeted the particular needs of technical communication and anything remotely useful was proprietary, ugly and expensive. It didn't help that our focus was still on paper-based documents and generating Microsoft Help files.
Some things have gotten easier - these days everyone is focusing on standards compliant *ML-based content (and dropping or minimizing the paper output). But in some ways it's more complex, with widely dispersed contributors, lots of user-generated content, and more dynamic authoring concepts (like wikis). Also users are expecting to instantly find exactly what they're looking for.
And the old challenges are still there:
When I look at what Drupal can do today with just core and a few standard modules, I can see it offers, at least in raw form, a big piece of what I was looking for almost ten years ago. There are still some really critical missing pieces - like good single sourcing and structured authoring tools - but nothing that's outside the realm of possibility given a little time and perhaps some outside help with the heavy lifting.
Very similar history and thoughts...
I became involved with CMSes a little bit later, right around 2003 or so. My first with open-source was with the Zope + Plone combo. I found it to be challenging for less technically capable groups and individuals, to install, setup and maintain.
After discovering Drupal and for slightly more than the last two years I have been experimenting and testing the various 3rd party modules available for version 6, for exactly the purpose that you have stated; "Building an awesome technical communication CMS". One goal would be a base profile aimed at technical communication as a whole, with possible variants for niche or special purpose technical communication roles and processes.
I've also been looking into various Linux distros for the same purpose, to produce a distro of one aimed at and for the technical communication community. I've recently settled on Ubuntu, although it could be easily ported to other Linux distros as well. With Live CD versions interested technical communicators could both try before installing, use UNetbootin to create a Linux/Drupal TC CMS on a USB stick, or alternately to use Wubi and run a Ubuntu/Drupal TC CMS as a Windows installable/uninstallable application stack.
Glad to know and see that there are others thinking along the same lines as I have. I found this thread while doing a recent search on 'Drupal+DITA' and will be cross-posting to LinkedIn and various technical communication sites I already know of and post to. Maybe at the very least we can get some interest and comments from the larger technical communication community. (My approach was slightly different too in that I was researching the RDF/Semantic web + Drupal angle.)
I have gone as far as producing a Drupal 6.x based site for one chapter of one technical writing community, The Charlotte Regional Chapter of STC (stc.org), located here: http://www.charlotteregionalstc.com/, but it generated little to no interest. I feel Drupal, collaborative authoring, and CMSes was well beyond that communities ability two years ago, but times are changing and more tech writers are now at least aware of the technology. I have recently turned off the RDF and Semantic web related modules, but it would be simply enough to turn them back on (and add others as needed) though at any point in the future. My plan is to eventually take back the site for purely production testing purposes, and have recently recommended they move to what the larger organization is now offering it's communities, both Chapters and Special Interest Groups (SIGs).
Unfortunately, and I'm sure others here experience this too, I have to temporarily shelve the fun stuff like researching and testing out Drupal and Linux to return to contracts that can provide me with some revenue. Just the sheer volume of reading consumes most of my time, with little left to actually run installs and testing. I've joined this group and subscribed to this thread, but with a new six-month contract starting in two weeks I'm not sure how much time I can contribute. I have collected quite a bit of 'notes' on various modules, both written and some still in my head, so maybe that is where I can help out.
As always I'm interested in hearing thoughts from others too. As to your last question in your originating post, yes indeed this would definitely be something awesome, even if we were only to accomplish little bits and pieces over time, eventually leading up to the larger whole.
What about leveraging the answers generated spontaneously by vis
On all sorts of sites, people generate short bits of insights and
answers to questions without even considering that they are creating
"documentation." And yet these are sometimes very timely and extremely
helpful, and thanks to archiving and searching get visited over and
over again.
The documentation system I'd like to see would create a path from
these quick, short submissions to more formal documents. Visitors
could post questions right to an FAQ, and useful answers could be
upgraded to stand-alone web pages. Furthermore, visitors could create
a path through related documents by suggesting what should be read
before or after a given document. Please see my articles explaining
these ideas further:
http://radar.oreilly.com/archives/2008/02/developing_an_i.html
Developing an improved online environment for educating computer users
http://radar.oreilly.com/archives/2008/01/two_tools_we_ne.html
Two tools we need to improve online information
I'd like to keep this discussion going
Creating avenues for the users of the documentation to provide feedback is definitely important. Tying the existing documentation more tightly into the feedback and knowledge creation interfaces of the forums and issue queue would be great too (the comments left at the bottom of each page seem to also be a useful genre for improving documentation). Creating portals to access other sources outside d.o., might be something to consider in order to maintain alliances that help improve the documentation network. But I think it is important that that as a group there is an ongoing effort concerning the quality and organisation of Drupal's official documentation.
I'd like to emphasise the word "official" in that last statement. I think people want to know that the hand-books are a solid place to begin their search for the answer.
D.O. has a strong position in search engines, and whatever issue people are searching for, if it has something to do with Drupal, they are more than likely to end up here (even if it doesn't have to do with Drupal, as the Lullabot team pointed out simply searching for "views" takes you to D.O) . We should provide them the best reception possible... what is the best way to do this?
I would like to say though, a good technical communication tool would win a some really good people to the side of Drupal docs.
I just wanted to pop in
I just wanted to pop in quickly and, in addition to supporting this all around, say that this came up at the Writing Open Source conference last summer, and all of the various OS projects which were there got very excited at the prospect of Drupal becoming a tool that they could all use for this very purpose. A lot of our discussion was around using Drupal as a front end for DITA work in addition to just a better management tool, and those conversations have helped inform the general idea of where we want to go with docs.drupal.org and the new IA. I should note that in the new IA work so far, the idea of custom content "maps" made from re-usable chunks of content will be our way forward, with book module pretty much gone. So that is definitely something we will be getting sorted out regardless of anything else on our wishlist. ;-)
As we move forward with docs.d.o we are going to need to come up with a spec so we know what we are shooting for and what is reasonable. As Lee noted in his original post, not all of the things being talked about here are necessarily what we want (or can reasonably accomplish) for our own site. I do think that sketching out a "pie in the sky" can help us see where our progress on our site can help move things toward that final vision though. Feel free to break out a subsection in our Community Initiatives to sketch more of this out, http://drupal.org/node/713766. We do have a tools section in there already as well which can be picked over/expanded, http://drupal.org/node/394420.
Learn Drupal online at Drupalize.me
More on the tools page
I've added some more stuff to the tools page and reorganized things a bit to sort things by domain (authoring, reader experience etc.).
I wonder if any of this features would be a candidate for the Google Summer of Code?
Let's do try to get it in SoC!
I think that's a great idea. There's a year's worth of work here for a developer and a year's worth for an editor. Perhaps a summer of each would get us going!
http://groups.drupal.org/google-summer-code-2010
Weighting, tagging, or voting
One of the issues with the Handbook is that all of the authoritative, carefully-thought-out stuff is right there as a simple peer of an enormous amount of chaff.
Of course, we should get rid of chaff. But on the other hand, we encourage people to create it, and that's OK.
But could we have a flagging, or voting, or weighting system that would mark articles as more authoritative? I'm working on the AJAX/AHAH stuff right now, and there is basically one article written originally by chx, which is authoritative and worthy. Then there are about 5 that are either weak, distracted, or on narrow subtopics. A user of d.o deserves to know what the "real" page is.
Looking forward to the super-new system.
Weighting & Rating
I also agree with a flag system, but my preference would be a more friendly "Was this article helpful?" at the end, which I see on loads of knowledge base sites these days. After a defined number of "No" votes the article can be flagged for review.
i can totally get behind
i can totally get behind that! it'd be a good way to track pages that need work but don't actually get issues filed.
Use for Solr ranking as well
This technique allows us to rank search results higher that are rated higher as well.
making it work in real life
The "documentation" for drupal looks like someone piled two copies of everything on top of a couple of hand grenades and pulled the pins. Almost everything is somewhere, in chunks ranging in size from pamphlet to sentence fragment, currently searchable only by Google*.
The most critical design criterion for a new system is leveraging the ongoing editorial and administrative effort so that things are labeled, filed, and cross-linked with the greatest possible efficiency.
I want very much to help, but I'm not fool enough to take a lead.
I'd love to be a part of the reengineering of the documentation.
Greetings all:
I'm new to the Drupal community and just itching to get involved in a big way. I've only skimmed over these comments and had to jump right in to indicate my willingness to help!
I have a strong programming background as well as an interest in writing, formal/informal, technical/non-technical, fiction/non-fiction. So, I'd be happy to give a shot at helping to develop any custom modules; it would be a great way for me to build my skills, contribute to the community, develop a portfolio. I'm also just dying to get involved in the restructuring and rewriting of the documentation itself. As a computer savvy individual who actively looks to find things in the documentation, I can say from my personal experience that it can be somewhat of a challenge to make use of the system as it currently stands. I think that there is a great foundation and lots of data; it just needs to be refined. I love to learn by reading the manual. So, I'd love to make sure that "the manual" is easy to use and read.
Count me in!!
For now...
The development of custom modules for this project is not happening right now. But if you're interested in helping right now, you can check out:
http://drupal.org/contribute/documentation - Info on contributing to doc in general - this will help you get started as a doc contributor
http://drupal.org/node/515870 - Current urgent projects in Drupal 7 documentation
http://drupal.org/project/api - API project, which is the module that is used to generate api.drupal.org - there are many issues there that you could take a stab at fixing, if you want to do some coding related to documentation
http://drupal.org/project/issues/documentation - Issue queue for handbook-related documentation
Open Drupal doc issues - Issue queue for programmer API documentation
We'd be glad to have your help on any of the above!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Improving the module underpinning of docs
I do think that LeeHunter is going to need help with his uber-project, @vegantriathlete, so your offer is appreciated. You should chat directly.
I also would love to see us have a book module that does a few things way better:
Gives book context in a better way. There has to be a better way than a block on the side that stretches down farther than you can think. A better approach to breadcrumbs? Depth is still a problem. Some cute javascripty thing might help here. We can do WAY better on giving context in the handbook. So often you land on a page and have no idea that the page right above it is the one you really wanted.
Improves navigation. "Next" should probably be the sibling of this page. Not child, not the uncle. Right now, there's never any indication which it might be.
Allows a reasonable technique to consolidate a portion of the book. Right now, you can print out a section of a book, but it is really, really ugly.
A bit of UI work on book module could make a huge difference to the handbook.
Yes, we'd have to sell it to the powers that be. But on the other hand, it's said that docs is going to be on its own site sometime, and that makes the sales job easier.
GSoC Proposal?
I am involved in email correspondence with Lee. In fact, I have pitched the idea of creating a proposal for Google Summer of Code. Would you guys be willing to help me out with the creation of a proposal? I think that Lee's vision and the comments posted here give a great start. I would be ecstatic to be given the opportunity to be a GSoC student for Drupal! In fact, @LeeHunter and @rfay have already mentioned GSoC in previous comments. I didn't even notice those when I posted my original comment.
If I have Lee's and your support, I'd be happy to start drafting a proposal. What do you think would be a reasonable project scope for a three month undertaking? I want to be ambitious enough in the proposal without getting myself in over my head and over promising.
@jhodgdon I have begun digging into documentation and making changes where I have edit capability, and submitting requests for changes (via email) where I don't have access. It's too bad that it doesn't show up in my Track tab on DO. I have filed an issue about this. I'll have a look at your links and see where I can pitch in there, too.
Thanks for your feedback!
I'm totally into making this
I'm totally into making this happen. As Jennifer pointed out, custom modules for docs.drupal.org itself aren't in the cards but, since many of the requirements are not necessarily specific to the Drupal docs, it would be very cool if someone started chewing on these pieces as a regular contrib project. Solving some of these problems might give us a big head start when it's time to build out the Drupal docs infrastructure.
The only problem I can see is that the deadline for the GSOC is almost here and some of these things would take a fair bit of thought and research, especially figuring out what can be leveraged from existing modules.
Note that many Summer of Code
Note that many Summer of Code projects have research as their first component. Lots of students don't jump directly into cranking out code. They investigate solutions and plot, so I wouldn't worry about that.
Absolutely!
So a completely do-able scope would be a complete revamp of the book module, as I've started thinking out above. That would have enormous value for the community and for D.O. I'm worried that this might be slightly too small for a full summer project, but it might not be. Wow, could there be some huge benefit.
If LeeHunter has some structure ready, that might do too, but I'm suspecting we'd be behind the 8-ball for that. It might be too big, or take too much time to define.
We can get custom modules into docs.d.o in the future. It just requires salesmanship, security reviews, and persistence. It's far more likely to happen if they're well known and publicly developed. Custom modules are being developed for the redesign as we speak, and d.o always has some varieties on it.
I'd be happy to help with the proposal and with mentoring, although I may be out of service for about a month this summer.
Book module
I love the idea of improving book module and I think that would be very useful to the larger community as well. One thing I want to flag though, is that there is a very real possibility that docs.d.o will not use book module at all. The new information architecture work is going in a drastically different direction than the classic hierarchical style that is central to the book module. At this point I am working on a basic assumption that we will likely need to create a whole new module for organizing the content. I certainly do not want to discourage work on book module at all, since it definitely needs the love and would benefit a great many people (including d.o). I just want to put it out there that work on book does not necessarily equate to work for docs.d.o.
Learn Drupal online at Drupalize.me
Don't use email...
Just a note: The proper way to report problems with doc that you cannot change is NOT by email. You should file an issue.
http://drupal.org/node/24565
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Looks like it's a go!
As I was posting the last comment, Lee was responding to my email. He's enthusiastic about me writing a proposal. I will get to work on a draft. Please help me out by answering the following questions:
I will get to work looking over the existing GSoC proposals and doing more research about the submission process. I will also have a careful look at all the comments already posted in this thread. I'll do my best to research existing modules to see what is already available that we can use versus what would need to be created.
Lee has told me that the application is due in less than a week. We'll need to move quickly. But, I would think that a bunch of documentation geeks could certainly write a good proposal!
Quite a set of topics
On #1. How does the doc system work/not work:
On #4. Way do-able is to gather information about a redesign of our traditional "Book" module (or an add-on to it) that would make navigation more effective. This could involve work with usability experts, research of other systems, etc. Then an improvement to book could be implemented in that time. Or an additional module that just helped with navigation feedback, etc. It could be all jquery.
On #5: Why don't you start a wiki page to do your proposal on. This thread will spin out of control shortly.
New wiki page
@rfay Thanks for the suggestion. Let's move the discussion here.
Initial research on existing proposals
Some things worth noting
Webchick made these points
I think that we can safely say that this area is not getting due attention.
I will demonstrate through the following analysis that nobody else is even approaching a proposal like ours.
Alex UA specifically made a plea for Views projects. Lee has already hinted at views implementation in this project. I don't know if it would be anything new to views, or just making use of the existing module.
There was a post to brainstorm accessibility ideas that seemed to be reasonably well received. Could we incorporate some accessibility aspects to the new design?
Rough analysis of existing proposals
I make no pretense that I understand much of what these proposals entail. I've only done a quick sorting into what seemed like the best categorization, from the greatest number of entries to the least. The contents of each category is just a cut-and-paste of the titles
New modules
Drupal Social API graph
Semantic assisted Natural Language Processing for extracting information from Nodes
Remote entities
Unified field manager
Object relationship mapping for drupal
Rules data transformation plugin
Autoupgrade, Install modules and themes via admin panel
An online test or education module
unified payment api
Tournament System
Optimise the evaluation of big rule sets
automated performance testing
Facebook-style Micropublisher
Flash Theme Engine for Drupal
Top Nodes with Google Analytics
Users and Groups management for multiple LDAP/AD
Drupal - JasperReports API :: bridge
Creating a generic Search API
Touch interface for mobiles
Animate Drupal API
Drupal APPcenter || Module browsing through Drupal Back End
Versatile Quiz Module
Bulk Menu Creator with a Toggle Switch
Bookkeeping module for Drupal commerce users
HTML5 support for Media (Drag and drop files, <video and <audio rendering)
Affiliate module for Drupal Commerce
freight exchange services module(s)
HR Employee Module
Desktop Content Manager - Adobe AIR
Round Robin / Hunting Assignment Queue for individual users or groups
Car Sharing module
Auto Taxonomy Generation from Node-Content
Upgrades to existing functionality
QueryPath update to D7
Drupal Commerce Usability: Bulk Product Creation / Import Tools
refactoring Drawing API
Overhauling the Search in Drupal 6
Date module rework
Intuitive interface for CCK & Views
Views Query Backends
ODF Import
Rewrite Drupal Update Process
Collaborative Editing of Nodes
Taxonomy with node-functionality
Integration with other tools or modules
Image Editor integration
Integration of Drupal with Open Office
Integration of a No-SQL Database
Integrating Views output into Feeds Module for further processing
Integration Engine on Drupal [DConnekt]
37 Signals Product Integration
New profiles/distributions
Install Profile for a PHPBB-like forum
Improving 'Eduglu' for creating better E-Learning sites
Drupal Installation Profile for E-Learning
What the analysis shows is that most people are suggesting new modules. Some of the modules provide more general functionality that can be used throughout the community and by other modules. Most of the modules provide specific functionality that would be used only by those who have a particular need for that module.
The next greatest category is enhancements to existing modules. Again there is a mixture of the general benefit/specific audience applicability.
There were a number of suggestions to integrate with other existing pieces, which in my estimation provide mostly specific audience benefits.
Finally, there were suggestions for new profiles/distributions. A common concern I saw with all of these proposals was that it didn't seem like a project that would take three months.
My conclusion
Our proposal will create a sea shift in the way the Drupal community functions (at least with regards to documentation). It has extremely broad reaching impact. I don't see that any of the other proposals come even close to the widespread benefit that this would produce. Additionally, we are looking ultimately to create an entirely new distribution that can be made available to the world. So, it's not only the Drupal community that will benefit from this undertaking; it's the entire open source community. Look at Dries' quote about how important the community is; it's not about the code. Our proposal is really about the community. The other proposals are almost entirely about the code.
Of course, we will build on D7, which will give a great test platform. And, as I asked about in an earlier comment, the possibility of helping to upgrade existing modules to D7.
Some points, since I've been
Some points, since I've been involved with Summer of Code for several years.
This is in fact, Summer of CODE. If there is no code involved, you are unlikely to get much support in the evaluation process. This has been a problem in the past, most notable in the theme and usability areas.
You should definitely target D7, this will by far be your best bet.
Timeline and deliverables are the key part of any proposal, and the ones that slack in these areas are most likely to get pushback. I'm not certain what the deliverables are here, or what you will end up with.
That's just off the top of my head, and I'm short of time, but should give you all some guidance.
You may not be able to do D7
If history serves, it may be a long time before docs.drupal.org gets to D7. You may have to do D6 work.
I believe that the preference is for proposals that target D7
I'll have to chase down where I read that. I'm fine with doing it in D6. I just think that the proposal will be better received if we pitch it for D7. But, let's find out more about that.
D7
Just for the record, docs.d.o will be built on D7. And as for getting the powers that be to sign off on things, I'm the main "power that is" for docs.d.o. While we obviously need to review things with as much vigor for security and performance, there will be fewer restrictions on features than for the main d.o site (one of the big reasons to split it into a subsite).
Learn Drupal online at Drupalize.me
Yeah!
Double Yeah!
I think D7 is the way to go, too.
Especially with the "small snag" I noted below. As this may not end up being a GSoC project anyway, the exact time frame of producing a ready-for-prime-time product is much more open. I think that we will thus have the freedom to start building it on D7 even before D7 is released; nothing but the latest and greatest for this undertaking! This project could provide some great testing for D7.
Do it for both
There's no reason you can't do it for D6/D7. Target it on D7 and provide a backport. That way all the needs are met. Technology and reality.
Small snag
I'm not eligible to be a GSoC student. Boo hoo for me.
But, I think it's still worthwhile putting together a proposal that a student could work on. I was interested in this project before I found out about GSoC and I'm still interested in it. Whether I can be the student, or whether it even ends up being a GSoC project is irrelevant to me. I just want to get working on it. So, I would still like to see us take this idea to a proposal ready state. Make sure to do so at the wiki.
Added some stuff to the wiki
I've added some content to the wiki. Basically just rewrote the title, added some background information and tried to give a sense of the scope of what might be addressed.
Well, actually the scope is still much too broad for one person to tackle over the summer, but it whittles things down a little bit and provides some possible directions that this could take.
Great changes!
I love the stuff you added. I was at the code sprint with GVS all day today. So, it was nice to come back and see such a wonderful addition to the wiki.
Don't think of it necessarilly as a replacement for books module
Kick ass! Wish I were eligible, but I'm going to be graduating before the summer. But if I may say...
I think we want to keep to the idea of how DITA regards topics, as being in and of themselves independent and without hierarchy in mind (though meta-data is attached to content and how this works needs to be discussed).
This ends up leading us to not only a separation of content and presentation, but also a separation from content and context.
In this fashion, the key module would seem to be something that enables dynamic use of context for determining hierarchy and suitability of which nodes appear on a page, and these nodes might have conditional content (kinda like tokens, so depending on what operating system a person uses, it might display a different file path).
This should be something that could be extended by other modules.
It would allow for the determining of hierarchy of multiple nodes on a single page. What I mean is that dita topics equal nodes. But a drupal documentation article might consist of multiple topics/nodes. This module might be something that displays multiple topic/nodes on a page depending on context. It would determine which topic gets an h1 tag, which topics are at the h2 level, and the hierarchy that follows even possibly to a paragraph and sentence level.
Context might be an installation profile, a level of ability as a drupaler, the version of drupal, or the operating system on which the site is running.
Does this make sense to anybody? Lee? Am I catching your drift? Main thing I think is to keep it extensible.
Yeah that's it exactly! The
Yeah that's it exactly!
The book module forces you to find the one and only one perfect context for a given node. And that's absurd because three different people might expect to find it in three different places. The only way to have it in two places (eg in both the Drupal 5 theming guide and the Drupal 6 theming guide) is to create a fork. And of course, once you duplicate something, the two versions start growing apart as one version gets revised and the second is overlooked.
And then sometimes, as you say, you might want multiple nodes to be displayed on one page so that the reader can get the whole story at once. Or maybe there's a chunk of text like a caution that could be a single small node that happens to be displayed on a number of pages.
My only small qualification to what you've written is that I wouldn't want to see level of ability as a context. I think we'd want to keep a context to something that's very clear and unambiguous (like product version) and it's not possible to draw a line between one level of ability and another.
Multiple hierarchies and context sensitivity
If you added a feature to the book module where it could have multiple parents (and it remembered how you got there) then you'd be somewhere, and that would be good.
I've seen other projects successful with the forking technique - forking EVERYTHING. It makes sense for API docs, but it doesn't make sense for everything else. But we still tag things.
I don't have an agenda here, but one reason to enhance the book module rather than completely change our framework is that we're more likely to get to completion. It's an incremental change, rather than an all-for-everything that has to be "completely done" before any value is achieved.
Real quick, there is already
Real quick, there is already an issue for multiple parents for book module (http://drupal.org/node/5901). It isn't hard to do technically in the code, it has never moved anywhere because there is no reasonable UI for actually managing it. The other issue with working on book module, is that it is still part of core, which means really working on it would be working on it for D8, and that isn't quite as useful to us in terms of docs.d.o.
I agree that incremental change is more likely to get done, especially with volunteers, but one of my goals at Drupalcon is to also figure out funding because docs.d.o is frankly not going to be the tool we want or need without cash and/or dedicated hours donated.
Learn Drupal online at Drupalize.me
Funding for the effort
First off: I recognize that I am a total newbie to Drupal and the Drupal community. But, having said that, I want to throw out the fact that I have all kinds of time on my hands right now. If we could arrange any type of funding, be it stipend/donations/chip-in I'd work full-time for really cheap. In fact, while I don't have any other paying opportunities, I would be willing to work full-time on it without pay; the only downside to that is that any paying gigs would necessarily take priority.
I know that I come on really strong. So, please don't take my enthusiasm as some desperate attempt to earn cash in any way possible. I am truly interested in the project. And, since there is not a tight timeline, my learning curve should not present an issue. I do have 12 years of prior programming experience; this would just be a matter of putting that expertise to use in a new way.
Please accept my apologies if I am offending (or annoying) anybody with my forwardness; feel free to contact me privately and tell me to knock it off, if I have crossed the line. My goal is to make it clear that we do have some resources (people-power wise) immediately available. If we could make some financial resources available, that would be great, too. Let's continue moving forward with what we have and see where it goes from there.
Lee said: My only small
Lee said:
Right, the module itself wouldn't have anything to say about what contexts the information designers create. It would leave the door open as much as possible.
@trevjs - You are eligible
Check out the FAQ.
putting the horse before the cart
Two vital programming proverbs keep going through my mind as I read this conversation:
"I can't tell if it works if I don't know what it's supposed to do."
"The sooner you start to code, the later you'll be done. The later you start to code, the sooner you'll be done."
What are the objectives? What are the specs? These are the key questions. I really don't care if new modules are used, or not, or new modules written just for the project, etc. I care about being able to find the info I need when I need it; I care about other drupal developers having the same capability; and I'm concerned with keeping administrative overhead as low as possible.
So I want to spend serious time on the first half of the list at Looks like it's a go!. Initial research on existing proposals is good raw material for what I'm talking about.
And incidentally, I suspect it will be most practical to do this for v.7. Multi-platform sucks, and the lead-up to 7 seems to have been better engineered than any version change before it.
So, what about a wiki page for objectives and specifications?
You should definitely use the wiki
We are compiling objective and specifications here.
I agree completely Neil, and
I agree completely Neil, and designing something only through the board here wouldn't work so well.
I think that right now the discussion is about what a hypothetical proposal would look like for a google summer of code project, or how to break things up into seperate projects. And also what the priorities are, and what resources need to be sought out.
In the case of GSOC, a spec would be a product of the research phase of the GSOC project. The mentor would approve the specification, and then the student would begin coding.
New dita-wiki mailing list
Just a heads up that there's a new dita-wiki mailing list.
Apparently IBM and others have been doing some experimentation with using DITA-based wikis to enable collaborative authoring of documentation. The list has only been running for a few days so I'm not sure how useful it will be, but I find it interesting that people are talking about bringing together the yin of wikis with the yang of DITA. That seems to be similar to what we're trying to with this discussion and with docs.drupal.org, facilitate both the authoring/collaboration side and the structural/coherent/semantic side.
http://tech.groups.yahoo.com/group/dita-wikis/
BoF at Drupalcon
If you're at Drupalcon and want to kick around some of these ideas face to face, please come to the "Drupal as a Technical Communication CMS" BoF.
We'll be in room 276 from 4:15 to 5:15 pm Tuesday. Hope to see you there!
We've talked a bit about
We've talked a bit about dynamic context in here. And there is this discussion going on in architecture that would have an impact on how we'd create modules to do this.
Or at least it would in the long run. Don't know yet how they are imagining it will work. It sounds like it stores variables for the context. Though I had been imagining something that stored an hierarchy of rules on when to react to a context. Anyways, was wondering if anybody else was following this who might know more, and be interested in commenting.
Do you have a link to the
Do you have a link to the architecture discussion?
I wasn't going to post it
I wasn't going to post it because I didn't want to direct people there who couldn't add to their discussion (which is mainly about how to test it, and variable scope and all that). But, I will do it with this warning, and its not for you Lee, but for anybody who might be watching. It would be bad to hijack their discussion I would think. But here it is: http://groups.drupal.org/node/63708
Great idea....be careful not to make the same mistakes
This is a great idea. But not a new one. Mnay folks have embarked on this path and been unsuccessful because they really don't understand the intricacies of technical content, the needs of the authors, the relationships that must be in place for an organization to adopt such a system and move away from standard tools and approaches. That said, if it were done right, it would be a HUGELY important addition to both the Drupal community and an attractive solution for many organizations that do not YET use Drupal.
I'd like to encourage this effort but also warn of the dangers.
One important fact to consider: component content management is NOT best handled with relational databases. Tables filled with data stored in row and columns do not have the same flexibility that XML-based repositories do. There is a move away from SQL type databases by the type of firms that would be interested in large scale implementation of a system such as you describe.
Additionally, this type of system must be able to support component content management and have an authoring environment based on DITA, content that is reusable and easily discoverable, and output to a variety of standard formats: XML, EPUB, PDF, HTML, etc.
It should also fully support the move away from text-only documentation. Video is increasingly replacing or augmenting text documentation and, with the move toward interactive documentation (a la the iPad and the EPUB standard) content objects stored in a Drupal-based system need to be able to address interactive elements and their reuse.
There are many, many, many issues to consider. But, the idea is good and the first organization that actually does it right, could become the defacto open source documentation hub.
There is a site that provides a great (although very basic -- and not a CMS) online editing idea -- it's called FLOSS Manuals and it allows users to create, edit and REMIX documentation for open source and free software. en.flossmanuals.net/
One of the coolest things about FLOSS Manuals that the developers have not fully addressed, but is a brilliant idea (and a much needed feature) is publishing the documentation output to a widget that allows the user to generate a piece of code and grab it, then paste it to their blog, intranet, Facebook page. Thus, providing a live connection to the documentation. The published documentation would be linked to the source documentation on the FLOSS Manuals site, meaning when the documentation is changed at the source, the other websites, intranets, social networking pages, blogs that have provided a copy for their users would be updated automatically. VERY USEFUL!
So, I hope you are able to make this happen and if you'd like some help brainstorming about this, I'd be willing to see if I could get a group of folks together to talk about it.
All the best,
Scott Abel, The Content Wrangler
+1 (760) 550-9321 scottabel@mac.com
blog: http://www.thecontentwrangler.com
twitter: http://www.twitter.com/scottabel
friendfeed: http://friendfeed.com/thecontentwrangler
facebook: http://www.facebook.com/scottpa
Very interesting idea indeed.
Very interesting idea indeed. I've been looking for a low-cost (or open-source) DITA CMS solution to enable collaboration for some time. The market is thin, though it is getting better.
I agree with Scott regarding the issues with a relational database. Having worked with relational databases for 15 years and DITA/XML for 4 years, they're both great technologies, but completely different animals. For a DITA or any other XML CMS, I am convinced for robustness, not to mention longevity and scalability, the solution needs to be a NATIVE XML database, not an XML-enabled one. There is just too much to be lost in the translation of trying to upload XML content into a relational database.
Regarding trevjs comment: on the DITA toolkit... "A more usable, and still open source, interface for this, or an alternative to this tool would be a worthy project indeed." ---> Yes, the DITA Open Toolkit is not for the faint of heart. You definately need a few technical skills to support it. But it gives you a great deal out of the starting gate: transformations to web and PDF formats out of the box, and a community building more translations and specialisations to leverage from. I know it doesn't fit everyone's business needs, but it fits a wide range of generic uses and when it fits, it is an incredibly powerful starting point. I'm not convinced there is value in time spent to re-invent that wheel. Perhaps improvements on its usability and definately its documentation - though that is getting better too. And the folks on the DITA UG are very very helpful.
RE: Native XML Databases
Based on Scott's and luellaj99's input on Native XML Databases I did a quick discovery search today and located this resource, (see below) which has a nice table view of Native DBs, links to a brief description on the same site and then links to the DBs home sites, downloads, docs, etc.
XML Database Products
http://www.rpbourret.com/xml/XMLDatabaseProds.htm
XML Database Products: Native XML Databases
http://www.rpbourret.com/xml/XMLDatabaseProds.htm#native
I would guess we would want to go with the open-source versions only, which narrows down the field considerably. The rest would then need to be reviewed for support of current (and future?) XML related standards. More input from the technical communication community?
Here is some additional links from that above table that I quickly reviewed that seem to have potential, but I have to admit this is brand new territory for me. My Drupal DB focus and research has been predominately for MySQL and more recently PostgreSQL.
Sedna XML DBMS
http://www.rpbourret.com/xml/ProdsNative.htm#sedna
http://modis.ispras.ru/sedna/
BaseX
http://basex.org/
Berkeley DB XML
http://www.rpbourret.com/xml/ProdsNative.htm#berkeley
http://www.oracle.com/database/berkeley-db/xml/index.html
XML Native Database Systems: Review of Sedna, Ozone, NeoCoreXMS
http://swing.felk.cvut.cz/index.php?option=com_docman&task=doc_view&gid=...
Showstopper?
If a native XML database is a prerequisite for an all-purpose tech comm CMS, then I guess that would actually rule out Drupal as a candidate.
Which would be a real shame, since the existing features and modules in Drupal could provide a huge amount of extra value to a documentation team.
:(
An all-purpose tech comm CMS...
... is not what I ever had in mind. Multipurpose yes, a panacea, do-all, solve-all problems, no. I still feel Drupal has the highest potential for providing the technical community at large with an alternative to commercial CMS solution, and is IMO already even better in many ways to proprietary tools and tools predominately in Windows.
I'd say that a Drupal-DITA-XML+Native XML database combo be a very long-term goal and variant, with something more generalized and multipurpose for the immediate or near-term. DITA is IMO not needed for everything or every doc project. Besides I prefer RDF/RDFS over topic-mapping and DITA, just a personal choice, we may eventually see a convergence between the two but I'm not going to hold my breath on that one.
IMO what is needed in the near-term is a simple to install and setup, 100% open-source CMS, that has a rich, flexible user-interface, text editor, with the ability to import and export to multiple formats. Drupal already has much of that in the form of modules and plug-ins, we simply need a tech comm profile. Something along the lines of an OpenPublish, but on a much smaller scale, but still with the preselected modules, template and functionality all in place, AND as important well written documentation on how to use it.
I don't think we can go the XML route
IMO, the XML route, while perfectly fine, would not fly socially. We're committed to "eating our own dogfood", and we're also committed to a whole community contributing. Both of these argue for hosting our docs on Drupal, in a database.
It is just we can't really
It is just we can't really begin with something that is clearly not what Drupal currently is. There are simply other aspects of this that are easier to implement. It would not be realistic to expect an enterprise system for technical communication to come about within a year. We might set ourself a goal of something that offers basic requirements such as single-sourcing, content reuse, and off-line editing. It would be a solution for small documentation shops, other open-source projects, and teachers who want to give their students an idea of how to compose documentation, but also want to give them some familiarity of a popular tool for general web publishing.
It is the teaching scenario that interests me the most actually. I don't think it is as important to teach a particular technology(such as XML) as it is to teach what that technology can do. Which is why an open source solution is needed, because people just need a way to learn the ideas behind it.
I think step 1 is making a case for why Drupal already is an asset for technical communicators. This would help us figure out step 2, which would be figuring out the simple solutions that would make it a better asset.
Would a "Drupal for technical communicators wiki" be a productive place to take this discussion? We already have some good things to share, such as how to implement DITA topic handling through taxonomy.
An asset for technical communicators...
"I think step 1 is making a case for why Drupal already is an asset for technical communicators. This would help us figure out step 2, which would be figuring out the simple solutions that would make it a better asset."
The first and greatest obstacle to overcome is getting technical writers setup with a WAMP/LAMP/MAMP stack first, the later two are not so bad as those groups of tech writers tend to be a bit more technically inclined vs. Windows users, and Ubuntu has a default Drupal+LAMP install. Not up to speed on what Mac OS X has to offer. I think this is inline with your 'teaching what technology can do' scenario. Oddly, the single most common request from members of technical writing groups I attended was training. !!! I'm predominately self-taught, I guess not all are comfortable with that path, or just haven't discovered it yet.
The next major obstacle I've witnessed and also heard is the learning curve for Drupal vs. WordPress, which I don't even consider a 'true' CMS, but it is what I see more and more tech writers now using for both personal and professional use. Confluence is also now becoming popular due to it's outputs to MS Word and PDFs, and IMO Drupal needs this badly. The single most dominate word processor in the US is still MS Word, even though 80% of business users use only 20% of the features. Tech writers may push it quite a bit more, maybe 80% of features.
For me personally I choose Drupal for it's flexibility and extendability, and the 1000's of free community modules and members willing to help you out with issues. The plug-in or module architecture sold me. Download, unpack, drop in folder, couple of sysadmin mouse clicks and in most case your golden. In that rare instance you need some sort of dependency the module documentation states it up front or it's in the help included with the module, or both.
Mike Bergman on his AI3 blog had an interesting 3-part series that I think addresses some of what is being asked here: http://www.mkbergman.com/882/listening-to-the-enterprise-total-open-solu...
I started looking into DITA
I started looking into DITA after Kristof Van Tomme's eating our own dog food session at DrupalCon. Came across DITALabs' DITA Enabler project. While built on the not very GPL friendly Xopus WYSIWYG editor, there seems to be support from the DITA community for an open source solution as well.
DITA-Wiki mailing list
The DITA-Wiki mailing list recently had a brief discussion about Drupal and DITA http://tech.groups.yahoo.com/group/dita-wikis/message/157
Drupal module for MarkLogic Server
I noticed this announcement today and thought it was pretty interesting since it indicates that commercial DITA-capable documentation tools are starting to provide integration with Drupal.
EVN Solutions Announces Drupal Module for MarkLogic Server
EVN Solutions - developers of pragmatic XML solutions for publishers - today announced the release of their Drupal Module for MarkLogic Server. The module enables content managed by the widely popular Drupal Content Management System to be stored directly in the MarkLogic Server. Once in the MarkLogic server, content becomes truly agile, leveraging all the server's powerful capabilities and enabling rapid implementation of new revenue-producing products and services.
Read more: http://www.sfgate.com/cgi-bin/article.cgi?f=/g/a/2010/10/27/prwebprweb47...
dojo session on DITA and Drupal
Tomorrow I'm doing a Dojo session on our work with DITA and Drupal.
After the presentation I would love to have a discussion with anybody from the docs team who can make it...
Register to Attend https://www1.gotomeeting.com/register/428898761
--
Check out more of my writing on our blog and my Twitter account.
Did this get recorded?
This seems really important - was a recording made? How can we watch it? Will you be at Vancouver?
http://drupaldojo.com/session
http://drupaldojo.com/session/documenting-drupal-next-generation
Additional notes and info
Additional notes, info, and some clarification can be found here - http://groups.drupal.org/node/107374
Gus Austin
Looking forward to your presentation!
We've talked about how this might be used in the cataloging of Drupal learning materials in the Drupal Open Learning Initiative (http://DrupalOpenLearning.org) and the Drupal Dojo, so I am very much looking forward to your presentation in the Dojo tomorrow (https://www1.gotomeeting.com/register/428898761). Regarding the document discussion after the presentation, I will hang on as long as I can for the discussion.
I had a great conversation with jhodgdon re documentation at the Seattle DUG a couple days ago and I hope to participate in a conversations with the Docs team leading up to the Vancouver Docs Sprint in December (http://groups.drupal.org/node/105309).
I've got client meetings all
I've got client meetings all morning PST tomorrow, so I won't be able to join. Hopefully Eric can fill Jennifer and I in on this in December, as it would be good for us to know what is going on here with your plans and prototypes.
checking off objectives
I've put together a wiki page based on the above identified features with some comments about the feasibility and a sum up of our current progress with the features I would like to see in an improved documentation architecture for Drupal.org at http://groups.drupal.org/node/109119 .
--
Check out more of my writing on our blog and my Twitter account.
Awesome indeed!
Wow. I just wanted to say how totally impressed I am at how far this has been moved forward in a relatively short period of time. When I made the original post back in February, it was just 'blue sky' thinking that seemed like it would be at least two years off, but it looks like the ball has already been moved even further ahead than I'd hoped.
I'm very keen to see this incorporated into drupal.org.
Glad you like our work!
Glad you like our work!
We've been working on these features for about 2 years now (e.g. Graphmind, we made a feature stack for Open Atrium with these tools) so your estimate was not so far off :)
But I was also surprised how all the pieces fitted together so well.
--
Check out more of my writing on our blog and my Twitter account.
Wow
Glad I found this thread!
Just so I am understanding correctly, it seems like this initiative is to improve 3 things:
When we are talking about restructuring are we considering some way to make it similar in scope to the way the Wordpress Codex is laid out? That's my hope, I find that documentation very easy to follow.
It seems like it will be inevitable that a lot of content will have to be manually ported to the new system whenever it gets built. (please prove me wrong here) I would be glad to help with that effort or really any effort to help keep this project moving. However, in the meantime thanks @jhodgdon, I was looking for ways to contribute to Docs and your links listed above are a great way to get started.
http://www.webbfx.net/
2 years later, how are people publishing to Drupal?
Scouring the Interwebs for info on how technical communicators are developing and publishing content with Drupal as the publication platform. What are folks doing today?
DocBookWiki - A documentation distribution
I don't know the results of this discussion, whether a distribution about documentation ever got built, but I like this idea. Actually I have created a module that can import, export, create and edit DocBook documents. It extends the functionality of the Book core module. Then I thought that it would be nice to built a distribution about documentation, which integrates all existing modules that extend the functionality of Book module, and maybe develops any new modules if needed. I have just started it:
- https://drupal.org/node/2069447
- https://groups.drupal.org/docbookwiki
If you are still interested on this topic you can join.