Airship/2019-SoD

= Airship 2019 Season of Docs =

The Airship project is excited to participate in the inaugural Google Season of Docs program! We look forward to welcoming interested Technical Writers into our team and our community, and plan to partner closely with them as colleagues and co-contributors to Airship. We also wish to leverage the creative ideas and interests of our collaborators to expand or refine the project ideas below -- we'd love for this to be a highly collaborative effort.

What is Airship?
Airship is a collection of loosely coupled but interoperable open source tools that declaratively automate cloud provisioning. Airship is a robust delivery mechanism for organizations who want to embrace containers as the new unit of infrastructure delivery at scale. Starting from raw bare metal infrastructure, Airship manages the full lifecycle of data center infrastructure to deliver a production-grade Kubernetes cluster with Helm deployed artifacts, including OpenStack-Helm. Airship allows operators to manage their infrastructure deployments and lifecycle through the declarative YAML documents that describe an Airship environment.

You can browse the Airship projects and source here, get an overview of the project here, and see some of the current documentation here.

Airship is currently a Pilot Project under the OpenStack Foundation, an Open Source organization which promotes the global development, distribution and adoption of open infrastructure with more than 82,000 community members from 187 countries around the world.

The Airship project team is excited to work with Technical Writers to craft quality documentation for developers and operators to get started quickly with the project. Matt McEuen, Drew Walters, and Kaspars Skels (mattmceuen, dwalt, and kaspars on Freenode IRC) have volunteered to serve as formal SoD Mentors, and the project will augment additional mentors as needed.

Season of Docs Project Ideas
The team has brainstormed a number of different documentation projects that would add loads of value to the community:

Project Name: Kubernetes Cluster API Integration Documentation
Description: Airship turns YAML file inputs into a fully-functional infrastructure build. The first step of that is to provision operating systems, the Kubernetes Kubelet, and other "bootstrapping" tools and configuration onto freshly racked-and-stacked servers, so that they can join the Kubernetes cluster being built by Airship. Airship's original custom implementation of declarative bare metal was to create the Drydock project, which drives provisioning using the MAAS (Metal-as-a-Service) tooling. However, the Kubernetes Cluster API has emerged as a nascent, industry-standard way to decoratively mange infrastructure for Kubernetes, and integration into this ecosystem is now a top priority on Airship's roadmap. The Cluster API also opens up additional use cases for Airship as a declarative provisioner of infrastructure hosted in public clouds.

Tasks and related material: this will be a learning curve for Airship's current users as well as for new ones. We would like to create documentation that outlines the following:
 * A clear rationale and overview for this change, and how it benefits our user base
 * Architectural diagram(s) that show how the Airship, Kubernetes, Cluster API, Metalkube, and Ironic projects work together in this context
 * A comparison of the "before" and "after" views to help developers and users find their footing
 * A guide on how to configure Airship for Cluster API-driven bare metal provisioning
 * A guide on how to configure Airship for Cluster API-driven public cloud provisioning
 * Additional information at the discretion of the Technical Writer and the rest of the Project Team

Project Name: Airship Architecture Reference
Description: Airship is a collection of loosely-coupled projects (Armada, Drydock, Pegleg, etc) which build sites using best-in-class tools (e.g. Kubernetes, OpenStack-Helm, Ironic). It can be challenging for a newcomer to quickly wrap their head around how these pieces fit together. A number of users in the community have requested a clear and concise Architecture Guide to help them envision the end-to-end platform before diving into the weeds of a site definition or a particular Airship project.

Tasks and related material: the proposed Architecture Reference would include the following:
 * Diagrams which clearly show the interaction patterns of the Airship projects and their interfacing tooling
 * Different use cases for Airship itself: e.g. Full bare metal site, Public Cloud site, or Edge site
 * Different workload use cases: e.g. OpenStack, CICD, or Containerized Network Function workloads
 * Clear description of the high-level requirements of the Airship projects, and links to project-specific details
 * High-level technical details of how the Airship architecture is accomplished -- interfaces, languages, tooling, etc
 * Additional information at the discretion of the Technical Writer and the rest of the Project Team
 * A slightly dated architecture diagram can be seen here

Project Name: Airship Developer Guide
Description: As with any open source project, one of the most important things is to get new developers up to speed quickly, and excited to work! Although Airship has a number of project-specific guides of various depth, and developer overview documentation, we would really like to optimize the developer experience to make it fast, friendly, and valuable. This project will focus on that outcome. The ideal Technical Writer for this project would be willing and able to get their feet wet with the developer experience, so that they can leverage first-hand experience along with input from the project team.

Tasks and related material: the proposed Developer Guide project would incorporate these activities:
 * Review of the various extant sources of Airship documentation, e.g. the different Treasuremap Guides and developer documentation for different Airship projects.
 * Creation of new documentation that focuses on the "developer experience" -- how to get started with Airship as a developer, and how to do normal daily activities such as create patchsets, test code, and participate in the community. This guide should be fun and painless for newbies!
 * Reference out to other documentation (e.g. project-specific dev docs) as valuable
 * Drive an appropriate level of consistency across different Airship developer documentation
 * Create any project-specific developer docs that are found to be missing and high-value
 * Additional information at the discretion of the Technical Writer and the rest of the Project Team

Project Name: Site Authoring Guide
Description: Airship uses a gitops-type approach to declaratively specifying what a built site should look like based on one or more git repositories containing a collection of YAML files. Since we push all of the configuration for the site into those files, they can be an intimidating set of YAMLs for a newcomer! It's important for Airship to provide solid guidance to new operators so that they can get started quickly out-of-box (we call this the "Batteries Included" approach) while also helping them understand how to take the next step and customize their Airship site definition for their specific hardware, workload, and use case.

Tasks and related material: the proposed Site Authoring Guide would incorporate these activities:
 * Review the existing Site Authoring and Deployment Guide to provide a starting point
 * Review the existing inline comment-based documentation in our example manifests. These can be expanded or referenced by this project as needed.
 * Split the existing guide up into consumable sections
 * Ensure that key concepts are explained so that new operators don't get lost
 * Assemble existing and new material into a few different "use case"-oriented guides, of increasing complexity: e.g.:
 * 1) a simple two-node bare metal lab (this should require little customization from the operator),
 * 2) a production-like environment with e.g. certificates, OpenStack configurations, and LDAP access control set up,
 * 3) a overview guide for adding new Helm-based workloads to an Airship, optionally using something like TensorFlow as an example