ExpressionEngine Site Strategy with Dev Docs

by: Dan Decker on: 4/25/2012

Documentation First! Wait, Documentation First?

You hear it often enough - “Documentation First!”, but for an ExpressionEngine project?

As the Community continues to amaze with the quality, depth and breadth of sites developed in ExpressionEngine, the need for a centralized dev doc repo becomes more important. The nature of projects being built with EE edge ever closer to web apps, with incredible add-ons that are almost apps in their own right!

Documentation may be the least interesting part of any development project, but you and your users will benefit by having high-quality documentation available.

Ok Dan, We Get It! Documentation is Awesome!

The ExpressionEngine developer of today needs a way to keep all this straight, and yes, Document First! Thankfully, Erik Reagan at Focus Lab (who is one of our EE Reactor team members) has recognized this need and is working on Dev Docs (still a beta). Why don’t you go grab that now, I’ll wait…

Excellent. Now that you have Dev Docs in your hands, take a moment to read the excellent readme.textile that’s included. Raise your hand if you have any questions.

Dev Docs is installed like other third-party add-ons for ExpressionEngine. Once you have the files in the proper places, we need to set the path for our doc files. This is currently done in your config file, but for the official 1.0 release it will be manageable from within the control panel. For now, you will need to add a new value to your ExpressionEngine config array. To do that, open /system/expressionengine/config/config.php and add $config[‘dd:docs_path’] = ‘/path/to/dev_docs/’;

Your Dev Document files can live anywhere on the server you like, even above web-root. And since they are files, they can be version-controlled. Yay!

With the config set, navigate to Add-ons → Modules → Dev Docs and click “Install” to install Dev Docs. At this point, if you try to access the Dev Docs CP, you’ll be greeted with an error, which is seriously no fun. We are here to have fun, so let’s write some documentation!

Choose Your Poison

Dev Docs is intended to make writing your project documentation easy (easy enough that you will actually DO it). To make that frictionless, DD supports Textile, Markdown and vanilla HTML. You can create one monolithic document, or breakdown your docs into sections that make sense for your needs.

Now that you have your text editor and format of choice, let’s go over the basics.

I like to keep things separated, so I create a markdown file for each section of my project’s documents.

  • 01-overview.md: the project from 30,000 feet.
    • Project goals and principals involved.
  • 02-addons.md: First-party, Third-party and custom add-ons.

    • Where to obtain them, how they will be used.
  • 03-content.md: Define channels, field groups and field settings for your content.
  • 04-url_structure.md: template-groups/templates and URL behavior.

    • The Map to your sitemap. The group/template that each URL accesses and what happens when you land there.
  • 05-environments.md: Particularly useful in version-controlled and staged server environments.

Your friend, H1
The Control Panel sections of DD are created using Heading 1. Any h1 that DD encounters will become a pill tab in the navigation. Use h1 to define your document sections, even if you have them broken down into separate file.

To give you an idea of how this translates:

# Notes for Awesome, Inc. Project

These notes are intended to be only for the developer(s) on the project.


# Site Overview

Awesome, Inc. has hired us to develop their new website.

They are a creative company with some interesting requirements!

## Team

This project is a joint effort of you and me:

- [Dan Decker](dan.decker@ellislab.com), Project Lead
- [You](you@rawk.dev), Project Developer

Note: anything above ::start:: will not be parsed by DD. It’s like documentation for your documentation!

In this tiny example, using Markdown, the text following the “#” will show in the Control Panel as a navigation item. Cool!

It Slices! It Dices!

You have your project. You’ve chosen your markup syntax. You’ve outlined your Dev Docs. Now what?

The meat and potatoes of any site is the content. You’ve been in meetings with our client, and we have the static mock-ups from the designers. As developers, we need to mesh those 2 things together into Awesome, Inc.’s awesome new ExpressionEngine powered web revolution!

Out of all this, several content areas and types have been identified:

  • The Homepage - A mix of Static and Dynamic content
  • Communication and Engagement (“blog” is so passé)
  • Static Pages - About, Contact/Thank you, Privacy
  • Portfolio
  • Staff Pages

Each of these channels has different content-types that have been identified and which determine the field types we will use in the channel’s field group.

A Note on Consistency - Naming Conventions and Defaults
It is good practice, especially working in a team, to establish and adhere to a naming convention and coding style. It keeps the team agile and fluid by letting any team member jump right in where another has left off.

Establishing defaults lets us maintain a general expectation and allows for the differences to stand out.

For example:

Across Channels, Custom Fields and Upload Directories we use the same naming convention. It's used to keep things organized and predictable. The convention uses a “prefix” of the Channel short name in front of any other words. For example:

- Channel name is “Pages”
- 3 custom fields for Meta Description, Primary Image & Body Content
- 1 Upload directory for the images
- The names would look something like:
    - Channel short name: `pages`
    - Custom fields: `pages_meta_description`, `pages_primary_image`, & `pages_body_content`
    - Upload Directory: “Pages Image Uploads”
    - This convention is used when applicable in Status Groups, Categories & closely related Channels as well.

**Unless otherwise noted:**

- Each Channel does not have custom category requirements
- Each Channel should use the default status group
- Field formatting should be "none" (rarely using XHTML etc)
- Leave field instructions blank
- Default Channel settings:
    - Default status: Open
    - Select 'Allow Comments' button in Publish page by default?: **No**
    - Automatically turn URLs and email addresses into links?: **No**
    - Enable Entry Versioning: **No**
    - Allow comments in this channel?: **No**
    - Display Rich Formatting Buttons: **No**
- File / Assets fields <strong class="upper">should not</strong> display "All" upload directories. They should only display the relevant ones
- Upload directory server path should be `{YOUR_DOCUMENT_ROOT}/uploads/{channel_short_name}`
- Upload directory URL should be `/uploads/{channel_short_name}/`

Channel Your Inner Documentarian
That’s an awful lot of groundwork!

Let’s make an example using one of our identified content areas. Using our notes from the client as well as the mock-ups from the designers, we have a really good idea of what needs to be on the homepage. However, our co-developer, Joe, has been on vacation (slacker) and this is the first he’s heard of Awesome, Inc.

Just because Joe has sand in his toes is no excuse for him to be unproductive when he returns. Lucky for Joe, we’ve been hard at work in Dev Docs. As soon as he gets back on Monday, Joe can dig right in on the homepage:

### Homepage

| Name                 | Short Name         | Type         | Required?  | Searchable?  |
| -------------------- | ------------------ | -------------| ---------- | ------------ |
| Homepage Welcome     | homepage_welome    | textarea/RTE | y          | n            |
| Homepage Action Call | homepage_action    | textarea/RTE | y          | n            |
| Homepage Marketing   | homepage_marketing | textarea/RTE | y          | n            |

##### Channel Notes
The Homepage will pull content from other channels and have content of its own. This makes it a bit unique.

- An image slider will be pulled from the Portfolio Channel
- "Tabs" with marketing copy
- "What's Awesome today!?" pulled from the Engagement Channel

The `textarea`s will use ExpressionEngine's native Rich Text Editor to allow the client to easily enter, edit and style content.

Which looks GREAT when you see it in the Control Panel!

With that, Joe knows exactly what we need for the homepage channel. He has a map for field types, their settings and a good idea of how those fields will be used in the homepage template. With very little friction, Joe can be productive after his fun in the sun.

That’s an example of a really simple channel, let’s tackle something with a bit more substance.

The Portfolio Channel looks tasty, and will require a bit more thought about the fields it needs.

The Portfolio is going to be used in at least 3 areas:

  • The homepage image slider
  • The Portfolio landing page - gallery
  • The individual highlight single-entry templates
### Portfolio

| Name                 | Short Name         | Type         | Required?  | Searchable?  |
| -------------------- | ------------------ | -------------| ---------- | ------------ |
| Portfolio Hero       | portfolio_hero     | file         | y          | n            |
| Portfolio Excerpt    | portfolio_excerpt  | textarea/RTE | y          | y            |
| Portfolio Detail     | portfolio_detail   | textarea/RTE | y          | y            |

##### Channel Notes
The Portfolio is Awesome, Inc.'s showcase of previous work. As one of the most important aspects of Awesome's business, it will feature in 3 prominent areas of the site.

- The homepage image slider
- The Portfolio landing page
- The item's detail single-entry template

The `file` field will direct uploads to the appropriate upload destination: `/assets/portfolio/`

`/assets/portfolio/` should be configured with image manipulations to create a `150px x 150px` variant for use on the Portfolio gallery landing page.

The `textarea`s will use ExpressionEngine's native Rich Text Editor to allow the client to easily enter, edit and style content.

The Hero field will be used on the homepage image slider and the detail single-entry page.

The Excerpt will be used on rollover on the Portfolio gallery landing page and the homepage image slider callout.

Even with more complex requirements, our teammates can dig right in, building this channel and supporting elements like an upload destination with image manipulations. Isn’t that great!

Get Cracking!

I would love to take you through every aspect of site planning with Dev Docs, but you likely have a method to your madness.

I hope these 2 examples show the benefit to starting your project with documentation. With Dev Docs in hand, you will always have a reference to fall back on when you have to come back to a project months later to track down a bug, or get a sense for how implementing a new feature can impact the overall site.

Dev Docs also makes a great way to provide client documentation. You can include step-by-step directions, screenshots, notes - you get the idea!

To hear about the official release of Dev Docs 1.0 follow Erik Reagan on Twitter and/or the repository on GitHub.

.(JavaScript must be enabled to view this email address) or share your feedback on this entry with @eecms on Twitter.

.(JavaScript must be enabled to view this email address)

ExpressionEngine News!

#eecms, #events, #releases