Skip to content
Planet Argon Planet Argon Engineering Handbook

Documentation

What goes where!

  • Standard
  • READMEs From “About Those Docs” by Daniel Abron: High level overview/description of project Architecture diagram Required dependencies (eg: Docker, language version, version manager etc.) Step by step instructions to install, configure, build, and run project on laptop Instructions for how to run all the tests Links to “Further Reading” (each should be a markdown file in the /docs dir), for example, but not limited to: Troubleshooting Workflows 3rd party integrations (one doc for each) Configuration Continuous Integration Environments

READMEs

Section titled “READMEs”

Application Overview

Section titled “Application Overview”
  • Client org name
  • One-sentence purpose of application
  • Names and links to relevant sub-modules, libraries, or related applications in the app’s ecosystem

App Diagrams

Section titled “App Diagrams”

Visualizations of common systems; used for onboarding and bug tracking.

  • App architecture
  • Data flow
  • FE Component

Project Dependencies

Section titled “Project Dependencies”

A list of the system prerequisites and dependencies that are required for set-up, development, and deployment. Provide commands for installing these dependencies, and note if they are platform specific. Mention which versions (should align with production stack)

  • Version manager
  • Prereqruisites (must be installed before application set-up)
  • Dependencies (must be installed for application to run once set-up)
  • 3rd party integrations
    • What services are used and why
    • Differences in local vs deployed use (is there a fake version or sandbox for local development?)
    • Configuration
    • Links to documentation

Project Set-Up

Section titled “Project Set-Up”

Step-by-step instructions on how to install, configure, build, and run project on development machine

  • rbenv install
  • Code block of commands to clone the repository and install dependencies
  • If no database setup is required, provide information on location of API & its documentation
  • If database setup is required:
    • Either command to copy database.yml.example if it’s present in the repo, or block of sample copy required for a development database.yml
    • Note if the migrations should be expected to run without error, or if the developer should generate a schema from the database
    • If applicable, note presence of seed file and provide command to run it
    • If no seed file is in use, note information for retrieving a database backup
    • Provide information describing the db backup strategy & frequency

Local Development

Section titled “Local Development”
  • App configuration
    • Location of DB host/name/port/password
    • Location of API keys
    • Process for obtaining .env file
  • Command to start local server
  • How to access the app locally in the browser
  • App specific notes
    • Dependency usage: Helpful notes or code block on dependencies (search indexing, background job processing, caching, etc)
    • Custom tasks: Helpful notes or code blocks for running custom tasks (rake, make)
    • Notes on directory structure; anything out of the ordinary?
    • Notes on significant diversions from framework conventions

Tests

Section titled “Tests”

Instructions on how to test the applications and what testing tools are used.

  • Summary of app test suite: latest code coverage analysis, list of testing tools used, list of manual tests required
  • Commands to run automated test suite
  • Step-by-step instructions for manual testing paths
  • Client expectations for UAT

Hosting

Section titled “Hosting”

Information on staging and production instances, assets, data API, and CMSs (when applicable)

  • Staging and production domains
  • APIs
  • CMSs
  • Asset management
  • Hosting vendor

Deployment

Section titled “Deployment”

Information on how to deploy and the checks and environments involved.

  • Overview of deployment workflow (e.g, local -> staging -> production) and if naming conventions vary
  • Deploying to staging
    • Staging server location/domain
    • Commands for deployment
    • How to access/query database from staging
    • Notes on tasks needed to be run manually before deploying, e.g, db migrations
  • Deploying to production
    • Production server location/domain
    • Commands for deployment
    • How to access/query database from production
  • How to access server logs
  • CI
    • Tools used for CI (e.g, Jenkins, CircleCI)
    • Where notifications go and how to respond
  • Exception handling
    • Tools used for exception handling (e.g, Bugsnag, Airbrake)
  • Performance monitoring
    • Tools used for performance monitoring (e.g, New Relic, Google Analytics, Pingdom)

Contribution

Section titled “Contribution”

Information about specific PR process for this project, if applicable

Troubleshooting

Section titled “Troubleshooting”

Issues that have been recognized but not addressed and ways to work around them; e.g.:

  • Set-up issues (e.g., different operating systems)
  • Failures in test suite
  • Failures in CI checks
  • Rollback plans
  • Issues w/3rd party APIs (e.g., is communication with the service logged somewhere?)

Workflows

Section titled “Workflows”

This section should explain how to go through the most common workflows in an application: e.g., an Applegate workflow would be logging in as a APGT staff member to the CMS and publishing new content; a Gnomon workflow would be saving a course and returning to the video to complete it later.

Engineering Team Handbook

Section titled “Engineering Team Handbook”

lorem ipsum

Confluence Project Space

Section titled “Confluence Project Space”

lorem ipsum

Client Wiki

Section titled “Client Wiki”

lorem ipsum

Issues/Tickets

Section titled “Issues/Tickets”

lorem ipsum

other resources for this section:

https://danielabaron.me/blog/about-those-docs/ ETM NOTES: THE TOPIC: “Documentation” received a low sentiment score (43/100) and hire priority score (3) in the DX snapshot on 12/19/22. Using the notes from our discussion on 11/15/22, let’s plan concrete next steps for improving documentation in our client apps:

Ben audits existing app documentation, noting: README quality Type of in-app documentation Out-of-app documentation (location, type, quality) Ben creates README template Team ensures existing apps’ READMEs contain all template info …

HOW WILL THIS IMPROVE THE CLIENT EXPERIENCE? This will make client apps easier for developers to navigate, increasing the speed at which they can do their work and onboard.

https://planetargon.atlassian.net/wiki/spaces/PADEV/pages/2261549057/2022-11-15+Planning+Team+Improvements+for+2023 https://planetargon.atlassian.net/wiki/spaces/PADEV/pages/2285010945/2023-1-10+Documentation+cont+d. How to access servers (address deployment issues) M1 macbook issues https://docs.google.com/document/d/19x1pcVnRG605FKU_oyKfQ2-5L2GHWTEMcyvBrh0KNf4/edit