Skip to main content

Wing documentation v2

  • Author(s): @boyney213
  • Submission Date: 2024-06-26
  • Stage: Proposal

Overview​

This RFC outlines changes and features for the Wing documentation v2.

Docs v2 aims to simplify the initial onboarding of Wing, organise content and define the information architecture of the documentation website.

The vision for Wing's documentation is to elevate the experience for all types of learners—visual, auditory, and hands-on. Getting started with Wing should take minutes and the documentation needs to be accessible (easy to find), clean (reduce noise) and automated where possible (e.g api docs, compiling example code in the docs against Wing, winglibs automation).

This document contains areas of refactoring and new ideas for Wing documentation with various implementation phases.

Wing Personas​

It’s important to understand and agree the target audience of Wing as the documentation will serve multiple users. These personas can be split into three categories, full-stack developers, platform engineers and contributors.

Backend developers - Backend developers building applications using Wing. These developers do not have prior knowledge of the cloud so terms need to be explained to them (i.e Queues, Functions, Buckets) and may be engineers that are in Kubernetes shops.

These developers are consumers of winglibs and the Wing standard library. They are part of stream aligned teams focused on the problem domain of the users of the business, not necessarily worried about infrastructure and operate with abstractions into the cloud.

Platform engineers - Engineers that are focused on building platforms for other internal developers, focusing mainly on developing custom platform providers or winglibs for the development teams to consume.

Often platform engineers may have system admin experience which they are more comfortable with Terraform than programming languages. Platform engineers may not be developers.

Platform engineers understand the basics of the cloud (Queues, Functions, Buckets). In fact they have deep knowledge of infrastructure and the cloud they run on.

Platform engineers are builders of winglibs and platforms. They are focused on agility within the business, building tools and platforms for engineers to move faster, with clear abstractions into their custom platforms and the cloud.

Contributor - Open source contributors to Wing. They may or may not understand the basics of the cloud and are looking for ways to contribute ideas, code and resources to Wing.

Full stack developerPlatform engineerContributor
How do they use Wing?Building applications using the Wing framework.Building infrastructure for internal teams through custom platforms or winglibs.Contributing to Wing
How do they add business value?Wants more focus on business logic and applications rather than worry about the infrastructure underneath.Wants to enable developers, avoid being bottlenecks and focus on business agility. They do this by abstracting away complexity, maximising automation and give developers a self service developer experince.
Level of understandingMay not understand the basics of the cloud (Queues, Functions), needs to be explained.Understands the basics of the cloud (Queues, Functions), does not need this explained to them.Understands the basics of the cloud (Queues, Functions), does not need this explained to them.
How do they learn?Benefits from how-to guides and examples. How to guides include things like deploying websites, deploying resources into the cloud, focused on business logic.Benefits from how-to guides and examples. More focused on how to create and maintain libs that others can use or examples of creating custom platforms.Benefits from how-to guides, either deploying applications into the cloud or creating libs and platforms for others.
How do they interact with Wing?Consumer of Wing standard libs, custom winglibs and custom platforms.Produces winglibs and custom platforms for others to consume.Can be both the consumer of Wing and author of libs.
TestingNeeds to understand how to test Wing applicationsNeeds to understand how to test Wing applications and libs.Needs to understand how to test Wing applications and libs.
Programming langugagesMay be interested in multi-lang preflight syntaxMay be interested in multi-lang preflight syntaxMay be interested in multi-lang preflight syntax
What level of understanding do they need with Wing?Needs to understand the core concepts of Wing and may need to the ability to dive deeper into Wing.Needs to understand the core concepts of Wing and deeper dive content.Needs to understand the core concepts of Wing and deeper dive content

Each of these personas have a different need for Wing documentation and may have different entry points within the docs. Based on these personas, the proposed solution is to organise existing content, introduce new sections/pages, add more automation into docs and develop a new patterns/examples page.

Sitemap proposal​

The sitemap below visually explains the proposed solution for docs v2.

Open the sitemap

Content has been marked with tags:

  • exists: content already exists
  • multi-lang: content needs to support multi-lang examples (TypeScript and Wing)
  • video: content can/should support video content in the future
  • interactive-tutorial: make the content interactive (with playground)
  • note: just a note

Install section​

Simple link in the navigation bar that will take users to install Wing.

Learn section​

The learn section is for people that want to learn Wing (currently “docs”), initially going through basics and fundamentals into progressively deeper content (i.e winglibs, platforms, Wing fundamentals). Users will initially learn core concepts of Wing through the tutorials in the getting started section. This will expose them to concepts of Wing including inflight/preflight, winglibs, testing and deploying.

Every time a concept is introduced (e.g Queue, Function, Table), users can click through to understand the fundamentals of these cloud resources. These will be new pages that will be added to the documentation under the Cloud fundamentals section in the Wing docs.

The learn section will also include platform and winglibs section giving users the ability to learn how to create winglibs and custom platforms (with supported videos), and give them the ability to dive deeper into these concepts. Winglibs section will be automated, pulling in content from the winglibs GitHub repository.

Pages highlighted with the “video” tag will also include videos embed within the docs giving visual learners the ability to learn Wing without reading pages of documentation.

API Section​

This a new section to the website, designed to contain deeper dive content. This contains the CLI user manual, Wing language details, API references and the language reference.

Moving this content to the API section allows us to keep the learn section clean and simple helping users understand the fundamentals and basics of Wing without needing to dive deeper straight away.

Within the learn section, anytime a term is used, links to the deeper dive content will be provided to them.

Wing patterns/examples (New)​

This will be a new custom page that will be designed for users of Wing and not a standard documentation page.

This interactive page will allow users to filter Wing content (i.e by language, resources) to see examples of Wing in action. These examples will be pulled from an external repo and contributing to them will require minimal effort from the community. The documentation will pull and index the examples/patterns and display them on the website (example https://serverlessland.com/patterns).

This new page gives users the ability to explore what is possible with Wing. Each example will have diagrams, content to explain the example, and authors of the example. Users may also be able to load examples directly into the playground (where possible). Users can use the CLI tool to clone these examples directly to their computer (used for analytics of popular patterns).

Each example/pattern will be it’s own page with opengraph and meta information. Leaning into SEO benefits. For example if users search for “Cloud Functions with Queues” or “SQS to Lambda” Wing examples need to show up in results.

Examples will include Wing standard library examples (i.e Uploading data to a bucket with a cloud function), and also Wing lib examples (i.e Writing a slack bot with Wing).

Examples and patterns are designed to be short, single page examples showing the code. If users want to dive deeper they will have resources on each pattern to dive deeper (i.e into the API section, GitHub winglib urls, Blog posts etc).

Implementation phases​

Here is a high level overview of the implementation phase for docs v2. The strategy is continuous improvement to the docs through small pull requests vs a big bang release.

  1. Updating docusuarus
    1. Updating docusuarus to 3.x.x from 2.x.x and required dependencies.
  2. Introducing new API section and organising pages.
    1. Creating a new API Section into the docs (nav bar / side bar)
    2. Focusing on moving and organising content into the relevant sections (no new ones yet)
    3. Adding redirects from old urls to new urls
  3. Creating new pages for the docs website and initial tutorials
    1. New page: Wing for application engineers
    2. New page: Wing for platform engineers
    3. Reusing / writing tutorials in the getting started section (has to support multi lang tabs)
      1. First Wing application
      2. Deploying
      3. Inflight & Preflight
      4. Testing
  4. Automating winglibs documentation into the website
    1. Setup automation to pull in winglibs into the documentation website
    2. Setup JSII for winglibs and backfill winglibs APIs for docs.
  5. Cloud fundamentals pages
    1. Creating new pages to explain the fundamentals of the cloud
    2. Including Tables, Queues, Functions, Buckets etc. (Linked to throughout Docs)
  6. New examples/patterns page
    1. Create a new custom page that allows users to explore Wing examples and patterns
    2. Create new mechanism that allows contributors to add them easily.
    3. UI must contain ability to filter for patterns.
    4. Examples https://serverlessland.com/patterns
    5. These examples will give users the ability to see Wing in action
    6. Users can clone the examples locally
    7. Each pattern/example will has associated documentation
  7. New migration & integration section
    1. New pages to help users understand how they can integrate with Wing if they already have (CDK/TF/CF etc).
    2. New pages to help users migrate from what they have (TF/CDK/TF) to Wing.
  8. Adding video content to documentation
    1. Adding video content for everything marked as video content in docs
    2. First focused on tutorials in the getting started section of the docs.
  9. Automating console screenshots
    1. New mechanism that will keep console screenshots up to date.

Summary​

This RFC proposes changes to the Wing documentation website, including Wing personas, required refactoring, introduction of new sections and an implementation plan.

The vision of the documentation for Wing is to create a first class documentation experience for Wing users. Users should be able to get setup with Wing within minutes and learn fundamentals through examples, interactive/written tutorials and clear/clean documentation. Users will be guided to deeper dive content where applicable throughout the experience.

Automation is key. Code examples within the docs will compile with Wing, and screenshots will remain up to date with the Wing console. Winglibs will be indexed into the documentation, and contributions to examples/patterns will require minimal effort.

Contribution is key to scaling the documentation. Review processes will be put in place to ensure new pages/content belongs in the correct location in the docs.

Once all phases have been complete in this document, we can review what is next and how we continue to raise the bar for Wing users through the documentation experience.

Appendix​

Research and inspiration from