Maintenance, operation, and handover design

Design a maintenance system after delivery

Many projects enter the operational phase with the understanding that ``it's over once it's delivered.'' Confusion will ensue later.The maintenance system will be designed and agreed with the client before delivery.It's a thing.

Clarify the division of roles in the maintenance phase

There are two axes to running a HubSpot site: technical maintenance and content operations. First, organize who will be responsible for what.

Maintenance contract types and content definitions

Maintenance request flow design

Handover document design to client

The handover document isEnabling marketers and content managers to run on their ownIt's for. If you write it from an engineer's perspective, the document will be too difficult. It is important to design your content to suit the audience.

Structure of transfer document

Module-specific operation guide template

If you have many modules, writing them all in one document will make it difficult to read. 1 page per moduleIn the style of The most commonly used format is to organize it in Notion or an internal wiki.

# Hero Banner Module Operation Guide

## What is this module?
A banner that displays a large image and catchphrase at the top of the page.
It is placed on the top page, service page, etc.

## Field description

| Field name | Contents | Notes |
|-------------|------|---------|
| Heading | Banner main text | Maximum 30 characters recommended |
| Subheading | Supplementary text below the heading | Optional |
| Background image | Background image for the entire banner | Recommended size: 1440x640px |
| CTA button text | Text to display on the button | Recommended maximum of 15 characters |
| CTA button link | Button link URL | External link opens in a separate tab |

## Recommended image size
- Width: 1440px or more
- Height: 640px ~ 800px
- File format: JPG (photo) / PNG (with transparency)
- File size: Recommended to compress to 2MB or less

## Things not to do
⚠️ Do not use vertical images (ratio less than 1:1).
   The layout may be distorted when displayed on a PC.
⚠️ When you use an image with text as a background,
   It may not be readable on mobile.

Module/template design with operation in mind

There is a difference between "code that works" and "code that is easy to operate." An hour of ingenuity during development can save dozens of hours of confusion during client operations.

Separation of the areas that marketers touch and the areas that engineers touch

How to write fields.json that is easy to operate

[
  {
    "type": "text",
    "name": "heading",
    "label": "Heading",
    "required": true,
    "default": "Enter heading text",
    "help_text": "Recommended maximum of 30 characters. If it's too long, your phone will wrap it back."
  },
  {
    "type": "image",
    "name": "bg_image",
    "label": "Background image",
    "help_text": "Recommended size: 1440 x 640px. Please compress to JPG format and 2MB or less.",
    "default": {
      "src": "",
      "alt": "",
      "width": 1440,
      "height": 640
    }
  },
  {
    "type": "choice",
    "name": "layout",
    "label": "Layout",
    "help_text": "Choose where to place the text.",
    "choices": [
      ["center", "Center (default)"],
      ["left",   "Left-aligned"],
      ["right",  "Right alignment"]
    ],
    "default": "center",
    "display": "radio"
  },
  {
    // Fields on STYLE tab are set as "For advanced users"
    // Detach from normal editing screen
    "type": "color",
    "name": "overlay_color",
    "label": "Overlay Color",
    "tab": "STYLE",
    "help_text": "The color to overlay on top of the background image. Transparency can also be set.",
    "default": { "color": "#000000", "opacity": 40 }
  }
]

Comment design for templates

The template file contains information for those who will touch it later (your future self or the engineer who took over). Leave a comment. From “What are you doing?”“Why did you do this?”The general rule is to write

{#
  =====================================================
Blog article template (blog-post.html)  =====================================================
[Use] Blog article detail page[Inheritance] layouts/base.html[DnD] None (fixed layout)
[Update history]2024-03-15 v1.2 Added content type form switching2024-01-10 v1.1 Added previous/next article navigation2023-11-01 v1.0 initial release
[Notes]- For tag naming rules, refer to "Tag Design" in README.md- The form ID is managed in the form_config dictionary in this file.- If you want to add a form, add it to form_config  =====================================================
#}
{% extends "./layouts/base.html" %}

{# ===== Content type determination =====
   Determine the type by the tag prefix.
   See Chapter 6, "Tag Design Strategies" for details.
   type: If multiple tags are attached, the last value found will be used (only one is recommended for operational purposes)
===================================================== #}
{% set ns = namespace(content_type="blog") %}
{% for tag in content.tag_list %}
  {% if tag.slug starts_with "type:" %}
    {% set ns.content_type = tag.slug|replace("type:","") %}
  {% endif %}
{% endfor %}

{# ===== Form settings dictionary =====
   Manage form IDs and redirect destinations for each content type.
   When adding a new type, just add it here.
   The form ID can be found in the form details URL on the HubSpot admin screen.
===================================================== #}
{% set form_config = {
  "blog"       : { "id": "BLOG_FORM_ID",       "redirect": "/thanks/contact"    },
  "seminar"    : { "id": "SEMINAR_FORM_ID",    "redirect": "/thanks/seminar"    },
  "whitepaper" : { "id": "WHITEPAPER_FORM_ID", "redirect": "/thanks/whitepaper" }
} %}

Coding and commenting conventions

When developing and maintaining code as a team, if there are no rules, the way the code is written will be inconsistent. Maintenance costs will increase.At least a clear written agreementis required.

HubSpot CMS Development Coding Standards (Recommended Template)

# HubSpot CMS Coding Standards
## File/directory naming conventions- File name/directory name: kebab-case (e.g. hero-banner, blog-post)- Module name: kebab-case + .module (e.g. hero-banner.module)- CSS class name: BEM (Block__Element--Modifier)- HubL variable name: snake_case (e.g. content_type, form_id)
## HubL Terms
### Variable definition- Define variables used outside the loop all at the beginning- Define the dictionary (map) with set and then refer to it- Use namespace (ns) only in stateful loop processing
### Template comments- Start of file: Enter purpose, update history, and notes (required)- Complex logic: write “why you did this” (you can understand what you are doing by reading it)- TODO: Make it easier to search with the "TODO:" prefix
### Existence check principle- image field: Check with {% if module.image.src %}- link field: Check with {% if module.link.url %}- Text: Check with {% if module.text %}- Do not refer to .src etc. without checking its existence
## CSS conventions
### Naming Convention (BEM).module-name {}              ← Block
.module-name__element {}     ← Element
.module-name--modifier {}    ← Modifier
.module-name__element--mod{} ← Element + Modifier

### Responsive- Mobile first (override breakpoints with min-width)- Unify breakpoints with CSS variables  --bp-sm: 480px;
  --bp-md: 768px;
  --bp-lg: 1024px;
  --bp-xl: 1280px;

### CSS variable references- Always refer to theme.json colors and fonts via CSS variables- Do not hardcode direct values ​​(#ff0000, etc.)
## Accessibility Terms- Set alt attribute on all img tags (decorative images are alt="")- Set aria-label on interactive elements- Maintain color contrast ratio at WCAG AA (4.5:1) or higher- Focus can be visually confirmed by keyboard operation
## Git commit message conventionsfeat: New feature addedfix: bug fixstyle: Appearance adjustment (no functional change)refactor: refactoringdocs: Changes to documentation onlydeploy: production deployment (used in conjunction with version tag)

Responding to HubSpot updates and regular maintenance

HubSpot is a continuously updated platform. By regularly adding features, changing the UI, and responding to deprecations, You can maintain the quality of your site for a long time.

Regular maintenance items and frequency

Areas most affected by HubSpot updates

• HubL deprecated functions: blog_recent_posts() Function specifications such as etc. may change. Regularly review the "Deprecated" section of the HubSpot developer documentation.
• Design manager UI changes: Even if the editor UI changes, the functionality is often the same, but the screenshots in the client manual become outdated. Recommended to be reviewed once a year.
• HubDB API specification changes: hubdb_table_rows() There may be changes to the query parameters. Be especially careful with sites that use HubDB extensively.
• Form embed script: js.hsforms.net/forms/embed/v2.js When the version of is updated, it is necessary to check the operation.

Common operational problems and solutions

troubleshooting guide

Basic techniques for HubL debugging

{# ===== Check the contents of the variable =====
   Be sure to delete it in the production environment!
===================================================== #}

{# ① Check the type and value of the variable #}
<pre>{{ module|pprint }}</pre>{# ② Check loop counter #}
{% for item in module.items %}
  {# Output loop status #}
  <p>index:{{ loop.index }} / first:{{ loop.first }} / last:{{ loop.last }} / length:{{ loop.length }}</p>{% endfor %}

{# ③ Confirm conditional branch (output judgment result) #}
<p>content_type: {{ ns.content_type }}</p>
<p>is_featured: {{ ns.is_featured }}</p>{# ④ Check HubDB data #}
{% set rows = hubdb_table_rows("my_table") %}
<p>取得件数: {{ rows|length }}</p>
<pre>{{ rows|pprint }}</pre>{# ⑤ Check request object (URL parameters, etc.) #}
<pre>{{ request|pprint }}</pre>

Regular performance monitoring

Structure of monthly performance report

If included in a maintenance contract, we will provide reports to the client on a monthly basis. Including the following items will increase credibility.

Long-term operation checklist

Textbook Summary: As a HubSpot CMS Developer