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

[laura s]

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:     bug reports
 Priority:     normal
 Assigned to:  karldied
 Reported by:  karldied
 Updated by:   laura s
 Status:       active

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?




laura s



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