Drupalcon documentation session
Submitted by sepeck on Fri, 2008-02-22 12:12
My session on documentation (Documentation - challenges, travails and myths) has been accepted and scheduled for Wednesday 4:45-6:00pm.
I hope to briefly cover some of the history and evolution of Drupal documentation, knowing the history is often important to understanding the present. Spend more time going over some of the present challenges of creating and maintaining documentation and debunk some persistent myths.
While the session is just over an hour, I hope to have feedback and participation, get some more people participating in one of the easiest ways to get started contributing to Drupal.
On Friday there is a code sprint, if you scroll down towards the bottom there is mention of non-developer activities and a documentation sprint so bring your laptops and get ready to participate.
I'd also like to add a thank you to those who have helped me out by contributing to my travel fund to get me there.
Theme by
Looking forward to it
Looking forward to your presentation. Especially the history portion which is where I often find myself hesitating to ask about things because I tend to assume (and not always correctly) that an idea has been discussed in the past.
...
Some ideas were technically not feasible at the time they were proposed, others were tried and failed. And we got a lot of things right, but people don't see it.It's a mix.
A thought => suggestion?
Since I can't be there in Boston :-( ...
I'm sure this is a recurring theme on the docs. mailing list/IRC or wherever.. Can I suggest/encourage/emphasise the value of documentation/information that addresses the how ("how do I get an image from my laptop into a post on my site") rather than just the what ("ImageThingumy module enables image upload using zeta-beta-flip and themeing/positioning/insertioning via a resizeable/movable/widgetable/usable device"). The functionality rather than just the technology.
A lot of the excellent info in the handbook is based round the technology (e.g. module name ordered A-Z). This is a natural way for the documentation to build up and is logical and easy to organise. But we also need to be able to get from the functionality axis into the technology axis. e.g. the contributed modules page is a great move in this direction.
More please!!!!!
e.g. in the Customization - Tutorials, HowTo and Snippets handbook, how do I know if I am looking for a Tutorial, a HowTo or a Snippet (i.e. how do I know the complexity of the question/problem I have)? This is all about moving from the solution space to the problem space - what are the questions that users are asking?
OK, that's quite enough drum banging form now - I was really only passing by. I'm probably preaching to the converted anyway, in which case, bring it on! Just a nagging thought that's been going round in my head for many months. Sorry for defacing your site, but it was this post that reminded me!!
Best,
gpk
like this page?
In the basic content management section of Getting Started?
Adding content with images - basic
Otherwise, the challenge is compounded by the flexibility that is Drupal. There are so many ways and differing preferences on how to accomplish a goal that it is difficult. The problem with just focusing on the modules by name, misses out on leveraging multiple modules in combination. A major theme I hope in my presentation is to try and encourage 'concept' articles. How to leverage different combinations of modules together.
In the end, all we can do is try and encourage people to click the 'Add a child page' link in the handbook and contribute as they are able.
Thanks for your comments.
Yes, that's exactly the sort
Yes, that's exactly the sort of thing - it's talking about images, and we do it using the upload module. Looks like we could still do with a few more concept articles tho' :P !! And, could we call that section something more helpful? It doesn't invite me to go exploring (if you want me to learn Drupal concepts you are better off teaching me how to do things, and I'll pick up the concepts by accident as we go. If you try and thrust to much theory down my throat it will turn me off.)
On second thoughts, the "Content, the Drupal way" page might belong better in the Content Management section (maybe at the back, for the interested reader). And the page on (interface) translations could become part of "Installing Modules, Themes and Translations" say. The bit on installing Drupal in a different language could perhaps go in "Install Drupal 5.x", or at least be linked from it. Then we don't need the concept articles section at all :P
As I said before I really hope I'm not banging on too much and perhaps I should start adding more documentation myself (only seem to have 2 book pages to my credit so far!!!). At least I *have* joined the docs mailing list today :) But I do just want to emphasise the value of writing for the audience who is reading this stuff. Easy to say, hard to do, as I know, and as you probably know better than me.
Best,
gpk
Post new comment