User documentation
twohills - March 11, 2006 - 04:36
"The Drupal handbooks offer a complete reference for those interested in Drupal, both novice and experienced Drupal administrators, Drupal users and Drupal developers." Boy that is leading with the chin :-D
Ok so where can i find getting-started-style documentation for my Drupal users please? For example:
how to use the search function
what blocks are and how to turn the optional ones off
different types of contetn and how to create them
what it is you are seeing with all the nodes on the front page
dig in. :)
Start at this part: http://drupal.org/node/258
You'll want intro to terminology
Basic site configuration
Look through mdoules just glance through here at the top level. The contrib modules has some great stuff but not all of them are documented here.
and of course the best practices link in my sig.
Seriously. Drupal is flexible. It makes it great for you to cuild a site fitted to your needs. Hard as hell to make quick outlines as no one writes many.
so random additonal http://drupal.org/node/40241
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
If you can't find what you're looking for
then maybe, once you've figured it out, you'll want to pitch in on the documentation effort. This is a community and we all pitch in how we can.
Laura
_____ ____ ___ __ _ _
pingVision, LLC • BlogHer • rare pattern • scattered sunshine
Doc for someone USING a Drupal-based website
No guys, read the post. I no longer consider myself a newbie. I'm not asking for doc for me. i'm not asking about someone setting up Drupal, I'm asking about someone USING a Drupal-based website.
What can I put online for all my end users to help them with thier first encounters with some of the eccentricities of Drupal?
If you don't find it, write it
Then you have the opportunity to write it so it's there when the next person comes along. I read your post. Are you reading the comments? We're a community here, and it lives on contributed effort. Maybe you can help on this score?
You also might look for existing material on Bryght.com and CivicSpaceLabs.org.
Method-wise, you could try the help edit module to put the assisting text on the relevant pages of your site. I'm sure anything you posted back here would be most welcome additions to the handbook.
Laura
_____ ____ ___ __ _ _
pingVision, LLC • BlogHer • rare pattern • scattered sunshine
Ahh, I see now. End user
Ahh, I see now. End user docs. Well, my suggestion is to look through the built in help files and go from there. Drupal instals tend to be a bit different for each audience and target group. So help for your site is not necessarily help for my sites, etc. That said, take a look in the Basic site configuration link I provided earlier and you will see, End user guide
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
many thanks, that's what i was looking for
or at least a start. I missed the obvious, that it was in the install instructions.
I think there needs to be a distinction made between user doc and technical doc - the two are muddied here. this user doc is hidden in the tech doc and after a few pages it reverts back to technical doc by launching into site configuration. So I can't just link to it from my site and leave them to it.
I'll figure out how to propose a whole new book, because that is what i think is needed.
Laura: if I sounded a bit sarcastic it is because the statement "The Drupal handbooks offer a complete reference for .... novice and experienced .... Drupal users" is pretty bold and the fact is it offers nothing of the sort...yet. If It should say "the drupal handbooks provide technical documentation and we look forward to someone doing the enduser doc". As a fairly non-technical person who has in one month taught myself Apache, mySQL, PHP and Drupal, and built a fully functional website, i've been kinda busy. But I am so delighted with Drupal and what it has done for me that i will be a happy contributor back to the community in future. In fcat i made my first "giving back" post yesterday :-D
We come back to my original
We come back to my original point. Your site is not my site and neither of our sites is theonion. Most devs and site admins as part of building a site provide documentation/instructions to use 'that' site. You mention you are new to this. Congratulations, welcome to the starting point of a lot of fun and new things to learn and do. Not everyone even considers end user docs like you have and it's important.
Those docs can serve you as a starting point to customize to your sites needs for your users. If you like feel free to add to them.
On some reflection, I moved them up a level in the handbook.
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
+1
twohills has a good point, which a few people have also raised with me, and I've brought up in the documentation list every so often - we need a separate end user handbook.
True, all sites are different, but we can at least document the common tasks.
The 'End user guide' you linked to above would make a useful starting to the handbook. Hidding it in the Installation handbook seems a bit strange.
Cortext Communications
Drupal Themes & Modules
Currently there is not
Currently there is not enough there. Second we go back to my original point. In my view, it is the individual sites installer to develop the docs to that persons site. Pointing end users to Drupal.org seems like a road to disaster. A given site may not have all of the features.... end users asking for help with features missing from their sites in Drupal.org's forums.
Drupal is a way for you to build your site with your features. You provide the land (domain name) and the infrastructure (web server, database, PHP). Drupal.org gives you a good set of raw materials to start with. Now you, the site architect must decide what is important to you, what features you will offer, how it will look and behave. You are building your own home. 2 bedrooms -3? and an office? A den? A fireplace? Kitchen sink?
I am not against the idea of a generic book, but I think that a site pointing their end users to Drupal.orgs end user docs is the wrong approach. Developing documentation for 'your' site is part of the site implementors responsibility. Therefore, Installation and configuration guide. (The first page has existed in the handbook since 2004).
People may not realize it, but documenting how to use a site is an incredibly (less glamorous) and important part of implementing a site for more than just a few people.
Every time someone has brought this up in the past, they have also brought with them assumptions of what this stuff should look like specific for their site. Very hard to write generic docs.
There hasn't been anyone adding to this stuff since 2004. Until someone shows a commitment to doing so, it should stay as part of 'you' building your site and supplying 'your' client the necessary customized documentaiton as part of the installation and configuration of said site.
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
You are quite right
everyone has different configurations and expectations and each site needs custom help (but I would love to point folk at a Drupal URL with generic help as a stop-gap, especially for alpha and beta users before we go live).
Having pondered a bit more, i wonder if every MODULE should have a snippet of end user help associated with it. Some do, vid. filter/tips but many only have a few prompts for admin. Others have a bit in the readme.txt where no end-user is going to find it.
The one that was particularly irritating me to start all this was the search engine. i had to read the PHP code to figure out that the reason I couldn't work out the "and" operator is because there isn't one.
[In this case, I've decided to use Google. No point in inventing new search engines these days. i think the benefits of a Drupal-aware engine are far outweighed by the benefits of a super-engine like Google. but that's another discussion.]
I did make some notes as I trawled search.module. I'll start a new thread with what i learned.
What do you think of the idea of a collection of documentation snippets?
Using Drupal Docs
True, every site is different - and the potential to make a completely unique site is one of Drupal's great strengths. However...
There are many common tasks that could be documented. We could have end user documentation for an out-of-the-box Drupal install - sure sites will get extra features added, but the basics will be the same for most of them: managing users, content, comments, interpreting logs, using search, etc..
- "Build it and they will come"
If we create an end user handbook I predict it will be the fastest growing section of documentation. It's the least technical material to write for the docs, and therefore the quickest and easiest.
Plus it would be a good entry point for new users to start contributing - which is important. We need to get more people turned on to the joys of writing Drupal documentation ;-)
The same principles apply to the documentation as to the code (and design and translation). Our efforts are much more effective when we share them.
Cortext Communications
Drupal Themes & Modules
We have a phpsnippets
We have a phpsnippets section that is fast growing without making it a seperate book. The end user guide was top level and ignored before, so it is top level again now.
We'll see. I am not so optimistic as you on this as I have tried before more than once to get people to do this. It's not 'sexy' like php snippets are. Feel free to lead the charge in getting those end user docs updated.
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
Challange accepted
Hey, thanks Sepeck.
Will do - even if I can only average one page week, that will still add up to a good bit of documentation.
Cortext Communications
Drupal Themes & Modules
Yep. I remember now btw.
Yep. I remember now btw. It was a top level page until January and got bumped down a level when I was moving lots of stuff. :)
Have fun. I suspect once you get a few pages added, it will be the level at which you want it to be. Also, don't forget that some modules have help pages and sub pages in the handbook/modules section that have additional help text/etc. The balance of what/where is always such a fun trick.
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
That's great
Thanks Stephen, that is a much better spot for it.
I like writing user doc. I'll make some contributions.
Thanks again
Rob