[documentation] [Documentation task] Installation and configuration book structure

Sat Jan 13 22:26:42 UTC 2007

Issue status update for 
http://drupal.org/node/108954
Post a follow up: 
http://drupal.org/project/comments/add/108954

 Project:      Documentation
 Version:      <none>
 Component:    Installation
 Category:     tasks
 Priority:     normal
 Assigned to:  karldied
 Reported by:  karldied
 Updated by:   sepeck
 Status:       active

Best Practices guidelines are part of installing and configuring your
site.  Before I wrote the first articles we had a tremendous amount of
support questions from panic'd people who lost their sites due to no
backups or inadvisable changes on their production sites.  I am
convinced that people just installing and configuring their sites need
to be exposed to this as soon as possible if only so we can ask if
they've done this.

An intro to Advanced section' concepts or whatever would be excellent. 
We have a diverse audience here, neophytes (who are power users but self
taught), people coming from other systems with assumptions that get in
their way, specialists who see one aspect of web sites but not others so
any way we can get a logical top page intro into the next steps
(advanced, whatever) to group the more complex areas would be good.  I
was mainly getting things out of the way so we could see what it looked
like.

sepeck

Previous comments:
------------------------------------------------------------------------

Fri, 12 Jan 2007 21:29:58 +0000 : karldied

Steve wrote: "Rewrite/re-org the Installation and configuration book.
Make it's primary focus installing and configuring Drupal core."

For simplifying the top level of the Installation book, I propose the
following: 

1. Rename from "Installation and configuration" to "Installation and
setup"
2. Shorten "Introduction to Drupal terminology" to "Drupal terminology"
3. Move "Drupal terminology" to "About Drupal" book
4. Move "Troubleshooting FAQ" to "Reference" book ("Customization and
theming")
5. Shorten "Drupal Distributions: CivicSpace installer and Community
Relationship Management" to "Drupal distributions"
6. Re-title "HOWTO: Advanced user's guide" to "How to find answers" (it
is 2 pages)
7. Move "How to find answers" to lead child of "Troubleshooting FAQ"
8. Shorten "Tuning your server for optimal Drupal performance" to
"Server performance"

To me, "configuration" is a term that encompasses "setup" and goes much
further, to include installing additional functionality, modules, and
themes. You configure modules and themes; you set up a site or an
installation. 

Feedback sought! -karldied

------------------------------------------------------------------------

Fri, 12 Jan 2007 23:45:31 +0000 : laura s

Thanks for taking a stab at this. Here are some immediate thoughts as I
read this:

/1. Rename from "Installation and configuration" to "Installation and
setup"
2. Shorten "Introduction to Drupal terminology" to "Drupal
terminology"/

+1 - Less is more (to say the least, though no less)

/3. Move "Drupal terminology" to "About Drupal" book
4. Move "Troubleshooting FAQ" to "Reference" book ("Customization and
theming")/

-1 ? -- My feeling is that the terminology is more relevant for people
getting down to brass tacks, like installation. The "About Drupal"
section is where people will want to see what it's about -- the big
picture. A "related link" in the About Drupal section pointing to the
terminology might be good to add, but to move the whole section there
doesn't quite seem right to me.

Re the Troubleshooting, I suppose it depends. Troubleshooting install
and setup issues should probably stay within the Install area, but other
kinds of troubleshooting, like problems that can come up in the normal
routine of website administration and maintenance, could reasonably be
found in Reference. Maybe install-related problems could be called
"Installation Troubleshooting" while other troubleshooting could be
titled "Website Troubleshooting" or something like that. IMHO....

/5. Shorten "Drupal Distributions: CivicSpace installer and Community
Relationship Management" to "Drupal distributions"/

+1

/6. Re-title "HOWTO: Advanced user's guide" to "How to find answers"
(it is 2 pages)/
/7. Move "How to find answers" to lead child of "Troubleshooting FAQ"/

-1 in that, to me, "How to find answers" seems kind of vague. After
all, isn't the whole Handbook how to find answers? Is "HOWTO:" a
convention we want to pursue? And if so, should it apply to broad topics
as opposed to specific issues (e.g., HOWTO: Override Date Format)? I
think "Advanced User's Guide" may be vague, but as a catch-all for your
non-basic material, it certainly seems fairly descriptive as a place to
find that non-routine kind of info and help.

/8. Shorten "Tuning your server for optimal Drupal performance" to
"Server performance"/

I'm not sure this is an improvement. It's about tuning the server, not
about server specs, so the latter might be a bit confusing. If you think
about search terms people are likely to use, "tuning" is good to have in
the title, imho. Another alternative might be "Server tuning
techniques".

Other impressions?

------------------------------------------------------------------------

Fri, 12 Jan 2007 23:46:06 +0000 : laura s

Not really a bug, is it?

------------------------------------------------------------------------

Sat, 13 Jan 2007 03:16:33 +0000 : sepeck

I am reluctant to rename 'Installation and configuration' because the
idea is for it to be Installation and configuration of Drupal (core). 
I'd like to see some more intro to customizing your site articles in the
beginning of the next section.

I've renamed to Drupal terminology even though I like the other better.
 The content needs some expansions and additions.  I added some more to
the taxonomy off a description from styro I found in the forums.  It
needs to stay the first item in that section.  I realize that people
like to 'skip' to the meat but I we use a lot of terms for very specific
things and I think people should have to jump past it if they're going
to skip.

Instead of .... HOWTO: Advanced user's guide what about 'Next steps' or
similar?  Something to group more then basic stuff and serve as an
introduction of what to do next?  Moved tuning to a sub page of this and
renamed it to 'Server tuning considerations" to see what it looked like,
it may be that "Server tuning techniques" looks better (comments?). 
Moved planning a website to a sub page (This needs a lot of love and
attention but the basic framework and ideas were solid, which is why I
left it published until someone could edit it).

Moved migrating from other software to the dev handbook.  That's not
really a basic end user type thing. 

Moved Troubleshooting FAQ to the end of the book.  We've had it broken
out in the past but then no one could find anything and none of the
regulars saw old stuff to update/fix which resulted in a lot of
duplicated content.  This flat all in has had far more activity and
updates then the old method.  We can revisit this but updating to 5.0
should go first.

Unpublished the CivicSpace page.  It's no longer distributed from their
site and that company has changed focus.  I will probably figure a way
to add it as a historical reference in the about section with an article
on 'distributions -history of' or similar.  It's an important piece of
our history but for now it's unpublished.

------------------------------------------------------------------------

Sat, 13 Jan 2007 18:21:44 +0000 : karldied

Good feedback. Agree with it all except moving migrating from other
software to the dev handbook. The dev hb is dev for Drupal, rather than
dev for one's site? But I can see it being in the dev hb also. 

sepeck: "Instead of .... HOWTO: Advanced user's guide what about 'Next
steps' or similar?  Something to group more then basic stuff and serve
as an introduction of what to do next?"

'Next steps' seems fine, but the page itself is mostly about where to
look for answers. Maybe there should be an overview page for this
section, and the 'where to find answers' part moved to the first child.
I think the idea of this section is to follow 'Basic site
configuration.' Maybe advanced site configuration? And how does it fit
in with Best practices guidelines? Just thoughts...