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

[sepeck]

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

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.




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?