Jump to: navigation, search

Difference between revisions of "Airship/2019-SoD"

m
m
Line 1: Line 1:
 
= Airship 2019 Season of Docs =
 
= Airship 2019 Season of Docs =
  
The Airship project is excited to participate in the inaugural Google Season of Docs program!   
+
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. 
 +
 
  
 
== What is Airship? ==
 
== What is Airship? ==
Line 12: Line 13:
  
 
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.
 
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 ==
 
== Season of Docs Project Ideas ==
  
 
The team has brainstormed a number of different documentation projects that would add loads of value to the community:
 
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 ===
 
===  Project Name: Kubernetes Cluster API Integration Documentation ===
Line 28: Line 31:
 
* A guide on how to configure Airship for Cluster API-driven public cloud 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
 
* Additional information at the discretion of the Technical Writer and the rest of the Project Team
 +
  
 
=== Project Name: Airship Architecture Reference ===
 
=== Project Name: Airship Architecture Reference ===
Line 40: Line 44:
 
* High-level technical details of how the Airship architecture is accomplished -- interfaces, languages, tooling, etc
 
* 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
 
* Additional information at the discretion of the Technical Writer and the rest of the Project Team
 +
  
 
=== Project Name:  Airship Developer Guide ===
 
=== Project Name:  Airship Developer Guide ===
Line 52: Line 57:
 
* Create any project-specific developer docs that are found to be missing and high-value
 
* 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
 
* Additional information at the discretion of the Technical Writer and the rest of the Project Team
 +
  
 
=== Project Name: Site Authoring Guide ===
 
=== Project Name: Site Authoring Guide ===
Line 63: Line 69:
 
* Ensure that key concepts are explained so that new operators don't get lost
 
* 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.:
 
* 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),  
+
# 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,
+
# 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
+
# a overview guide for adding new Helm-based workloads to an Airship, optionally using something like TensorFlow as an example

Revision as of 21:59, 22 April 2019

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.


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.

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

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


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.

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.

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