Write more of an intro section for the Site Building Guide [#1125224]

The first section in the Site Building Guide - the Site Builder's Toolkit - goes straight into Features, then other misc. items, some more relevant and current than others.

Suggestions:

- Create a genuine intro section that introduces basic site building concepts on a high-level. One of these could discuss deployment issues and mention features. Then have the Features and other detailed specific documentation below. This high level intro section could go inside site builders toolkit or above it.

- Pull the "best practices" section out of the site builders toolkit. Edit this section so the first page is more comprehensive and matches the internal detailed pages more close. Best practices for site builders are important and should be on the highest level.

- This is the only guide that is labeled with the audience "site builders". The Structure Guide goes over content types, blocks, views - should "site builders" be added as a audience to this one? It doesn't make any sense for a site builder to dive into the Site Building Guide without understanding the concepts Structure Guide first.

Comments

Comment #1

arianek commented 12 April 2011 at 20:14

+1 on on all of that!

lisarex is starting a massive content review that doesn't include docs, but she'd be a good person to ping to get second opinions on this stuff as well, if i'm not around on IRC.

Comment #2

Carolyn commented 12 April 2011 at 20:15

toolkit: http://drupal.org/node/627302
best practices: http://drupal.org/best-practices

Comment #3

lisarex commented 13 April 2011 at 17:16

Issue tags:

+drupal.org content audit

+1 !

Docs can be round 2 of the content audit but first would like to focus on d.o. non-docs content first which is probably the most un-loved part of Drupal ecosystem right now.

Carolyn, regardless if you or someone wanted to write/assemble these improvements, they could get incorporated into Docs pretty easily.

Comment #4

arianek commented 14 April 2011 at 00:13

absolutely - i'd be into helping review this in may (want to focus on getting the d7 core modules done before i move onto anything else)

Comment #5

arianek commented 19 April 2011 at 20:19

Issue tags:

+Sprint: May 2011

earmarking this as a potential may sprint issue

Comment #6

Carolyn commented 26 April 2011 at 20:00

I moved the Site Building Guide around a bit. I found a section called "contributed modules" and moved that on top, since it seems to discuss general concepts. Below that is the section for Best Practices. The Site Builders Toolkit is now empty. I believe this section was supposed to show very useful, commonly used contrib modules or tools. It didn't have quite the right content for that. If we repopulate that section, I would consider renaming it.

This is my brainstorming for how to organize a Best Practices list:

audience: site builders, business planners/non-technical site admins
- first time drupal users/builders/themers/developers
- users who might write/adjust small pieces of code
- also point to more in-depth coding standards

Planning your site
-- plan your site, wireframes
-- writing requirements for functionality, etc

Choosing modules
-- choose modules to meet your site requirements
-- consider how your site might expand in the future (phase 2)
-- how to evaluate modules - maintenance, security, # of downloads, documentation

Backup
-- always make backups of db and files
--- methods for backing up (b&m module, server, where to store)

Participate
-- getting involved
-- document your way to understanding

Plan for the future/budgeting
-- estimating matainence costs
-- more modules, more complexity = means more to maintain
-- drupal has security updates (see update guide)
-- plan for upgrading - do not hack core

Testing
-- test against site requirements
-- follow the going live checklist

Deployment
-- configuration and content issues - in db
-- how Features puts config in code, views exports, other methods

Beyond Sitebuilding
--- if coding or theming, follow the coding standards
-- streamline tasks with drush
-- test your theme
-- test your code

Comment #7

arianek commented 26 April 2011 at 20:46

that looks great - i guess i would suggest a slight modification to the order:

- planning
- backup
- choosing modules
- plan for future
- testing
- deployment
- participate
- beyond

rationales: as much as i hate to make participation an afterthought, that is the order i'd generally approach things. also think it's important to make backups an early step, so people don't leave that and forget about it. ;)