LeeHunter organized a BOF gathering today at DrupalCon San Francisco related to his thread here about building an awesome technical communication system.
Here are my notes from the session. Enjoy, discuss, etc. They are a bit rough, but hopefully readable...
Lee's Goal: Make a tech communication platform that everyone will want to use, based on Drupal
Addison's Goal: docs.drupal.org, new IA, new tools (not necessarily the same thing as Lee's platform)
Lee's thought: docs.drupal.org becomes a proof of concept and first implementation of at least part of the feature set.
kevee has created a working system that is at least a good start towards what we need to do. Hopefully will post a screencast and report on his system.
==> Big issue is taking existing content and atomizing it
Things to think about:
-
Authoring environment
- external tool? on the web site? Framemaker?
- Not sure what the tech challenges are with integrating external tools with Drupal.
- Maybe make that one way to do the input, but not the only way, so as not to exclude folks
- Use a plugin architecture so that different tools can be used for authoring
- Needs to support the architecture (DITA, RDF)
- Needs to support organizing/packaging
- Needs to support finding topics for organizing into maps
- Needs to support adding notes to a map
-
Architecture
- DITA - conceptual framework for doc organization - Breaks content up modularly into "topics". Includes also an XML markup language. For tech communication, open and widely used standard in the tech communication field.
- Basic idea is to have "topics" that are small stand-alone pieces of information that are single-sourced. Then you can make "maps" that group topics together into outlines, books, etc.
- Also useful to be able to attach notes to topics on a map-by-map basis
- Semantic web / RDF - also needs to be supported
- May need other ways to categorize topics, if only to find them when building maps
-
Organizating and Packaging and relationships
- How to organize the topics into maps (books, outlines, etc.) and present them in a meaningful way
- How to relate document items to each other and see related information links
- Think large. On d.o right now we have 6000 printed pages, about 4000 nodes. Other systems may have many more pages/topics (like 10,000 from kevee in the session). How do you make a system to support finding the topics in this scope of a system when you are making maps?
- Visualization tool to visualize the relationships between topics.
==> Crell just added a project http://drupal.org/project/views_tree that will follow nodereference relationships and make a tree display for a view
-
User interface
- Don't want to just have hierarchy
- Realize that people will be searching
- Landing pages and tagging rather than hierarchy
-
Integration into applications
- Probably not what we plan to do for Drupal, though it could be useful
- Contexualization of doc in the application source
- Doc system needs to have hooks for this
-
Social issues
- How to get people organized to follow the structure
- How to get things ready for volunteers to write/organize doc
- How do we address people feeling frustrated at the lack of perceived progress
-
docs.drupal.org
- Want to build on Drupal 7, so we need to wait until it's OK to do that in the d.o repository, can't do that right now, but it will eventually happen.
- We need to focus on the D7 doc now rather than working on docs.drupal.org
- Addison's plan:
- Need to figure out the IA, which will drive the goals for the site
- Then we need to make specs and mockups that fit the goals
- Then we need to build the tools, hopefully by funding people to do it
- Then we need to migrate the doc to the new system
Comments
Thx for posting. Main point: Need to focus on D7
Thanks for posting this!
Biggest point in my opinion is that this can't move forward until d7 is off the ground. I'm looking forward to a week and a half from now when I can get back to playing a tiny role. Not all of us are good enough to be #7 ;)
If people are willing to comment, I'd like to inquire though about:
Is this in regards to quality of documentation? Or the speed at which things are moving? I'm not trying to provoke comment, just curious if there is something that people might wish to add.
Last thing, I just watched the keynote, and Dries made it particularly clear that the distributions were a major selling point for Drupal. Creating a good technical communication CMS installation profile would make for a good teaching tool for universities in teaching a web 2.0 version of technical communication. This isn't my idea b.t.w., but its one that I think has promise.
But of course "Talk is silver, and code is gold." Documentation is...? Hopefully, I'll get the chance to contribute a bit of each once I finish my thesis.
Thanks for posting these
Thanks for posting these notes, Jennifer!
Trevjs: I hadn't considered that this profile could be a tool in institutions teaching technical communication. That's a very cool thought.
I'm also starting to think that this platform might be a potential solution in my current workplace where we do enterprise architecture (i.e. high level IT planning) in a large organization. We're supposed to be the people thinking "architecturally" and promoting reuse, but our dependence on MS Word and the file-system-as-database means we can't efficiently manage and reuse our own content. There are all kinds of crazy things my group could do if we could refactor our artifacts into discrete chunks. Stuff like integrating consistent shared models and providing different ways to understand and explore our complex environment.
kevee posted his information
Just a note: kevee posted his screen shot here: http://groups.drupal.org/node/64903
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon