Project Guide

5 minute read

Project Documentation

Important principle on project is to understand why you are creating content, primary driver for creating must be for reuse by someone else on the project. It’s important that documentation is seen as a journey not a deliverable. Everyone should be using documentation as a way of sharing knowledge with another person on the project. The documentation that is written without an audience on a project is wasted.

This is a sample TOC that can be used as a starting point for projects, you may not require all of the sections but at some point in your project question and need for information will arise and will require a placeholder to communication knowledge to the team.

  1. Project Library

    1. Management Design

      1. Knowledge Management

        1. Project FAQ - Getting started with documentation

        2. Keyword Index - auto generated from page Tags


        4. Recent Activity

      2. Deliverables - list of all deliverables

      3. Roles - team, support, ops

      4. Guidelines

        1. Task Management - Jira usage, stories, tests, bugs

        2. Knowledge Management - Confluence usage, specs, review

        3. Page Specification - Template Description

        4. Component Specification - Template Description

          1. User Story

          2. Acceptance Criteria

          3. Behaviour Driven Testing

      5. Meeting Notes

        1. Meetings

        2. Retrospectives

        3. Discovery Sessions

      6. Reporting

        1. Status Reports

        2. Reporting Documents - list of pages tagged for reporting

        3. Automated Test Result Reports

    2. Component Design

      1. Project Artifacts - project repos

      2. Style Guide - Style to Component Mapping

      3. Unique Pages

        1. Page Specification
      4. Component Catalog

        1. Component Group

          1. Component Specification
      5. Content Hierarchy

      6. Dialogs - Shared Dialogs

      7. Frameworks - Design Frameworks listing

      8. Scaffolding - Forms that will be used by Authors

      9. Blueprints - Site templates

      10. Styles - General Styles applied to all components

      11. Tag Namespaces - Tagging for Content

      12. Dictionaries - Labels for component

      13. Templates - Available Templates

      14. Workflows - Workflows to be built

      15. Error Pages - Error pages that will appear

      16. Translations - Translations to be used

      17. Selectors - Selectors available

      18. Services - Services available

      19. Dashboards - Updates to Dashboards

    3. Platform Design

      1. Architecture

        1. Logical Architecture

        2. Physical Architecture

        3. Service Architecture - service, data, interfaces

        4. Delivery Architecture - ci/cd cycles

        5. Content Architecture

        6. Information Architecture

        7. Testing Architecture

      2. Config

        1. Development Config

        2. Workstation Config

        3. Tools

    4. Operations Design

      1. Content Migration

      2. Integrations Services

      3. Service Licensing

      4. Environment Config - service addresses

Component Specification

Content specification is the single document which is used to describe the component to be build and all of the relevant information needed. From this document a developer can determine if the component can be built. The whole team spends their effort to ensure this document is in an acceptable state so that developers can carry out their work using this document as a guide.

The document covers these main areas

Management Authoring Design
User Stories Component Summary Component Hierarchy Acceptance Criteria Test Cases Authoring Dialogs - Design - Content Related - Tags - Dialogs Variants Badges Theme
Input From BA, PO, TS, DEV, DES Input From BA, DEV Input From BA, DEV, DES

Project Artifacts

When starting an AEM project it’s important to get the initial project artifacts created early, as refactoring of code later will be complicated and time consuming. Creating Project artifacts early puts in place placeholders for content as the team progresses through the project.

  • Parent - parent repo used to contain all of the repo and build sequences, project primarily used to managing builds and scripting

    • Component Suite - repo from common component that will be build in the first phase

      • Services - repo for all Services that will be built

      • Content - repo that contains initial site content

      • Author - repo that contains all of the updates to the Authoring interface in AEM

      • Config - repo that contains all of the configuration setting

      • API - repo containing all of the API related services

    • Showcase Suite - repo for Static content used by the Testing Framework and for demonstration of components for use stories

    • Testing Suite - repo that contains the Load Testing

    • Prototype - repo for UI prototype

    • Deploy Suite - contains all of the Ansible deploy scripts

      • AEM - repo that contains all the AEM program itself and its initial configuration

      • VM - repo that contains all of configs for building VM Templates

      • Docker - contains all of the Docker configs

      • Jenkins - containing all of the Jenins configurations

      • Security - contains all of the Security, CIS VM hardening playbooks

    • Training Suite - repo containing the Training site

Naming Convention

Sample project hierarchy naming convention

  • {project}-aem-parent

    • {project}-aem

    • {project}-aem-author

    • {project}-aem-common

    • {project}-aem-services

    • {project}-aem-content

    • {project}-aem-showcase

    • {project}-aem-training

    • {project}-testing

    • {project}-prototype

    • {project}-deploy

    • {project}-docker

    • {project}-jenkins

    • {project}-security

    • {project}-vm

Project Archetype

Recommended practice to build AEM projects is to use Apache Maven tool. To make it easier to create new project Adobe maintains a Maven Archetype that consist of basic project and content structure as well as has the required project dependencies. More information on how to use the maven archetype when creating new project can be found here AEM6 Archetype more AEM5 Archetype.

At the high level an AEM project consist of Bundle and Content packages. Bundle package contains all the code that is required for the Application, it should contain any services, servlets and helper functions. Content package contains the configuration content, all the component configuration and code as well as Designs content. Its a best practice to divide projects into multiple project as soon as first release occurs. This help with maintenance, bug fixing and dependency management. It also creates a practice of ensuring that component and code does not become tightly coupled.

Project Concept to Creation

Knowledge Flow Map

The diagram below illustrates how a business concept flows through the necessary parties to get to the desired end state, which is a functional component that can be tested (and passed) on a showcase site, so that the business owner can utilize it in the organization’s production environment.

image alt text

Evolution of Artifacts

All artifacts on a project evolve over time and give input in other artifacts.

image alt text

Development Flow

This is a high level flow for development cycles

image alt text

  • Build Deploy Test: Developers work on local environment which is a replicate of target production, using same codebase as build server and performs all Build, Deploy and Test functions on local instances of AEM

  • Maven Dependency Resolution: Local Developers build environment uses centralised Maven repository to resolve dependencies in Build cycle

  • Commit: Developers code is commit code to Code repository

  • Tracing: Code is linked to Stories by Story ID added to each commit

  • Trigger: Each commit triggers a Build Test Deploy cycle on the Automation server

  • Build Tracking: Build tracking is reported into Jira

  • Build Artifact Storage: Build Artifacts are stored in Jira to be used in Depoy cycles

  • Build Test: Automated testing of Code is performed after Build an before Deploy cycle

  • Build Analysts: Automated Code Quality review is performed after Build an before Deploy cycle

  • Deploy: Deploy cycle is triggered automatically and manually to a defined environment


Leave a Comment