Documentation

# Save the Children Documentation

This is documentation files for Save the Children repository.
To get started writing documentation see readme.
To navigate, click on links below to dive deeper.

# Table of Contents

# Documentation README

This page provides an overview for documenting the STC codebase. Any documents created per the outline below should pertain to compiled scripts and large-scale functionality. Function-specific API documentation should be added to the source using code comments in JSDoc format.

The resulting documentation will be compiled and sent to STC for reference. It will also be used internally for future maintenance. Therefore, descriptions should be clear, concise and comprehensible to anyone with working knowledge of the required technologies (ie. Luminate, HTML, CSS, JS, Vue, etc...) but little or no familiarity with the codebase.

# Where to save documents?

All documentation should reside within subfolders of the /docs folder. Create new subfolders for major sections/functionality as needed. For example, if documenting the Sponsorship Acquisition functionality of the site (compiled asset /js/stc-sponsorship.js) the document should reside at /docs/sponsorship/stc-sponsorship.md.

All documents should be formatted with Markdown (opens new window) and saved with an .md extension.

# Document Anatomy

The following sections should be included in the document unless marked (optional) or not applicable to the feature/functionality being documented. Each subheading below corresponds to an "H2" header with the exception of "Title", which should be an "H1".

# Title

A short but meaningful title. For example, # Sponsorship Acquisition (/js/stc-sponsorship.js).

# Overview

A general overview of the feature/scripts being described by the document.

# Globals

Specify notable global variables/functions exposed by the script(s) using a bulleted list.

# Key Functionality

Create a subsection for each notable feature/function. What qualifies as "key functionality" will vary based on the scope of the document. If documenting a major site section, such as Sponsorship Acquisition (/js/stc-sponsorship.js), some examples of key functionality include:

  • children Vue component. Renders array of sponsor children w/ pagination.
  • featured-sponsor-children Vue component. Displays featured sponsor children.
  • sponsorship-search-filter Vue component. Allows filtering of sponsor children.
  • SponsorshipMatrix class. Responsible for ordering sponsor children per the client's specification.

Alternatively, if documenting a specific feature or piece of functionality, such as the Luminate Asset CDN, some examples of key functionality are:

  • CDN Distribution List (DEV vs PROD)
  • Asset origins and how they work. Which assets are pulled from Luminate/S3.
  • How CORS is handled
    • By S3
    • By Luminate origins (Lamda function)
  • How CDN assets are referenced in Luminate (s-tag)

# Code Structure

Bulleted list of filepaths and/or globs with brief description of the files.

# Example

Below is an example document.

# Sponsorship Acquisition (/js/stc-sponsorship.js)

## Overview

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.

## Globals

* `sponsorshipSetup()` - Bootstraps sponsorship app.  Called on Window load.
* `eventBus` - Event bus object used for passing event notifications between
  components. Initialized at startup.`

## Key Functionality

### Children Vue Component

*src/js/sponsorship/components/sponsorship-children.js*

Encompasses all sponsorship acquisition landing page functionality.
Fetches sponsor children from ODS and sponsor child quotes from the
Luminate Quote API then stashes both to local storage. Etc...

### Sponsorship Matrix Class

*src/js/sponsorship/library/sponsorship-matrix.js*

Javascript class which accepts an array of sponsor children and orders them
per the logic described in the objects `schema` property.  This class allows
the Children component to display sponsor children in the desired order
(ie. female, female, male, female, male, female, etc...).

## Code Structure

* `/src/js/sponsorship/components/*.js` - Vue components.
* `/src/js/sponsorship/mixins/*.js` - Vue mixins.