Learn how and why to create a "live" version of your authoring guide directly inside of AEM using the components you are documenting, creating an always current and single source of truth for authors, strategists, designers, and stakeholders, also enabling robust regression testing as your component library evolves.

What is a live authoring guide / brand library?

There is a constant need to enable authors to create digital experiences independently, using existing capabilities to reduce reliance on development and avoid over-proliferation of the component library. Strategists need to know the available experiences to deliver their content. Designers need ready access to existing patterns when new variations are requested by business stakeholders. And when new component variations are created, testers need to ensure existing content is unaffected.

An apparent solution to these challenges is strong documentation, but we've all felt the pain of documentation becoming outdated almost as soon as it's created. With the velocity of change in digital experiences, AEM authoring component guides are a prime candidate for quickly falling out of date.

Importance of a live authoring guide

A live authoring guide provides value to numerous stakeholders, resulting in increased efficiencies, improved reuse, and reduced costs.  Here are some of the ways different team members benefit from a live authoring guide:

Author benefits of a live authoring guide

• Readily see components and styles available for creating experiences

• Learn how to create the demonstrated content experiences

  • Read authoring instructions included in the guide
  • Review dialog and style system configurations

• Experiment with content modifications in a safe sandbox

Content strategist benefits of a live authoring guide

• Know what experiences are available to deliver and personalize content
• Plan for both component capabilities and limitations (example: content length)
• Ideate complete experiences, not just copy and imagery

Designer and Product Owner benefits of a live authoring guide

• Understand current components and variations to iterate from for enhancements
• Build out a new brand that promotes reuse of existing components and variations
• Ensure that your team is working off current state versus a potentially outdated style guide

QA/UAT Tester benefits of a live authoring guide

• Significantly reduce effort to create content for testing
• Regression test changes to modified components across all variations
• Regression test changes to reusable components across sites/brands

Developer benefits of a live authoring guide

• Reduce repeated content creation across different developers and testers
• Enhance the ability to spot unintended side effects of developer modifications
• Provide a live representation of base design elements (colors, typography, etc.)

Tips for live authoring guide content

A live authoring guide is only as good as its content.

Inconsistent content can lead to confusion, frustration and eventual non-use. Irrelevant content can reduce understanding. Incomplete content can result in only partial benefits. Here are some tips to ensure that your live authoring guide content is that maximally valuable:

• Have a consistent, predictable page structure. For example: Title, Description, Default Showcase, Alternate Showcase
• Use real, business-relevant content rather than “lorem ipsum” text and FPO imagery
• Always start with the most common experience created with a component
• Provide a consistent level of detail for authoring instructions across components
• Demonstrate all style variations for each component
• Keep pages to a digestible length, mixing content variations into style variations

Technical considerations for a live authoring guide

A live authoring guide can largely be created and maintained using the standard, non-technical authoring capabilities of AEM. At the very least, however, the technical team must be engaged on the topic of view access to the live authoring guide.

• If accessible to anyone (inside or outside the org) with the URL, configure search engine crawling to ignore the pages (example: robots.txt)
• If accessible to internal users only, restrict access using dispatcher and/or CDN controls and AEM access permissions, as appropriate

It is highly recommended that the technical team assist with keeping the live authoring guide in sync across AEM environments, particularly if it is being used to aid regression testing or by authors as a sandbox for experimenting with guide content. Storing library content within the code base is generally recommended, as it provides the following benefits:

• Automatic authoring guide sync across AEM environments
• Regular “reset” for guide content that has been experimented with
• Streamlined development and testing process and efforts

Additionally, having the technical team create and support dedicated authoring guide components and page templates, generally a one-time effort, can provide the following benefits:

• Ease of creating guide content
• Consistent and predictable page structure
• Differentiated page style and navigation from the main website

Frequently asked questions

1. Does a live authoring guide in AEM replace the living style guide the design team maintains?
   1. No. The design team’s living style guide is created prior to your AEM components being built, and includes technical specifications to aid in the development. However, the live authoring guide in AEM always represents the current state of what is actually implemented, and can also be used to help bring an outdated design style guide up to date.
2. Since the live authoring guide lives as content within AEM, how does the technical team help manage it?
   1. Content in AEM can be exported as XML files, stored within the code base, and then deployed to other servers from those XML files. You can choose to either have the technical team both create and maintain the guide content using tools that readily sync content paths between the code base and a local AEM server, or you can have business users create the content in a shared AEM environment and the technical team export the content via AEM package manager to then be included in the code base.
3. Can a live authoring guide be built using Edge Delivery Services?
   1. Since the live authoring guide is built with your standard AEM (traditional or EDS) components and authoring practices, yes, a live authoring guide can be built using Edge Delivery Services if your site and components are.