• Created by Unknown User (aizhamal) on Jan 30, 2019 5 minute read

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Status

State: Draft

Discussion thread: 

JIRA: https://issues.apache.org/jira/browse/AIRFLOW-3788

Motivation

Open Source Software needs to build a community to ensure its healthy growth. One of the tools used to build a community is the web site dedicated to the product. The goal behind building an open source friendly website for Apache Airflow is to engage, inform, and educate visitors, and ultimately to convert visitors into users and users into contributors, thus increasing the adoption of the product.

Introduction


This document overviews the general requirements for Apache Airflow website. It includes a list of necessary functions, capabilities, and/or characteristics related to Apache Airflow website, as well as the plans for creating it.

Apache Airflow website, like the rest of the project, will be open source, and accept community contributions. It will make contributions easy and approachable, while enforcing a set of best practices for developing the website and its content.

Improvements will also include a contributor’s guide that easily introduces prospective contributors to the community, and the process for starting to contribute to the project. It will also clarify the different kinds of contribution areas, such as  code, community development, project vision, documentation, bug reports, feature requests and any other constructive contributions.

Knowledge Architecture

OSS projects’ websites typically include several standard pages, where each page is formatted with a navigation bar on the left.

Taking from best practices and based on other OSS websites -- Apache Beam, Apache LibCloud, and others. A preliminary knowledge architecture for the website is provided in the next section. We outline important pages that are must-haves for OSS websites. As we advance in our project development, we will iterate the list and include necessary components that may be missing.

Home Page

Apache Airflow’s Home Page is the primary entry point to the site that contains project description, news, invitation to join the project. The homepage is divided into three sections that users can navigate by scrolling it down. Each section goes into further detail about Apache Airflow’s features, usability, and contributions. The structure is presented below. (For a more detailed description of the website structure see the appendix).

Section 1

  • Logo and Title

  • Short description

  • Link to the Quick start or (Learn Apache Airflow basics) which will be crosslinked with Documentation

  • Downloads

  • Announcements (can be crosslinked with Community)

Section 2

  • Apache Airflow features

Section 3

  • Use cases

  • Testimonials?

  • Communication channels, site map

Other must-have pages:

  • License Page: mention the Apache License 2.0 and link to the git license file

  • Downloads: page where Apache Airflow will release code. Downloads page describes the release/update/features and has links to the download pages that redirect to https://Apache Airflow/downloads/

  • Documentation: this page describes the project documentation, including guides, tutorials, and links to external documentation.

  • Mailing Lists: page will include user@, dev@, and commits@ mailing lists that the community might be interested in, and this page contains mailto: links that allow easy subscription (and unsubscription) to any of them. Private@ mailing list can be listed as well, but the subscription won’t be available.

  • FAQ: this page will include frequently asked questions and answers to them.

  • Road Map: this page will have a description of the project’s vision of future community or development activities.

  • Source Code: page will have links to the browsable source repository and git commands to check out the sources.

  • Coding Standards: page will include a description of the coding standards for submitted code by the community, along with a description of how strict the project intends to be.

  • Issue Tracking: page will have links to the JIRA or other issue tracking tool.

Proposed organization of must-have pages in Top bar items:

  • About

    • A Brief History of Apache Airflow, license

  • Documentation (kept in Pydocs)

    • Guides, tutorials, and links to external documentation

    • FAQ

  • Community

    • Roadmap

    • Events and meetups

    • Mailing lists, slack channels, interest groups

    • Jira bug tracker, StackOverflow

    • Code of Conduct

  • Contribute

    • Contributor guides

    • Contributing Code

  • Blog

  • Downloads

Website Generation Tools

Several options are being considered as a tool for generating Apache Airflow website, such as Hugo, Jekyll, etc.

Regardless of which tool we use, the website should be maintained in the git repository, and include the site generation tool as a binary file. This simplifies the process of site generation and enables changes to the site to be made by any committer.

Since the site is independent of the code, it should exist high in the git repository, e.g. parallel to the trunk of the source tree.

Content generation

Content of the website will include both auto-generated Pydocs for Documentation page and static front-end pages for the rest of the website.

All content will be developed and added by contributors.

Server and Hosting

Needs to be open source friendly - source code on GitHub along with the codebase

  • GitHub ?

  • “Netlify” claims to be free for OSS.

Testing

A number of tests, and checks should be written to ensure that changes and contributions to the website are of high quality, and that its appearance will not break or be disrupted by new contributions.

  • Automatic staging of changes for review

  • Checking for dead links

  • Possibly a spell checker

Action Items

The following is a comprehensive list of high-level action items.

  • Create a directory in the Apache Airflow repository to house the website

  • Determine the tool to be used to generate the website (Hugo, Jekyll, ..)

  • Create the knowledge architecture of the website

  • Create and receive approval for the design of the website

  • Create and receive approval for an initial prototype for the website

    • This prototype can be committed into the GitHub repository

  • Iterate to build an MVP

  • Move pages from Sphinx documentation to the new website

    • Team members, contributor’s guide, etc.

  • Build a set of tests for the website

  • Build a script to host and update the website

  • Change the website to the new landing page, and start receiving PRs from the community

References

Appendix. Detailed structure

Homepage

Section 1

  • Title

    • Apache Airflow

  • Short description

    • One or two short sentence(s) to describe the product, e.g. “Airflow is a platform to programmatically author, schedule and monitor workflows.”


The same page MUST have links to:

  • Quick start or (Learn Apache Airflow basics) which will be cross-linked with Documentation and include:

    • Overview

    • Tutorials

    • Examples

    • Guides

    • Videos

  • Downloads

    • Links to download different version of the product

    • Features and improvements

  • Announcements (can be cross-linked with Community)

    • Upcoming events

    • Meetups

Section 2

  • Apache Airflow features

    • Include icon and description

Section 3

  • Use cases

    • Companies that use Apache Airflow

    • Testimonials

Top bar items

  • About

  • Documentation, which will link to the existing https://airflow.apache.org/ website.

  • Community

    • Roadmap

    • Code of conduct

      • Airflow contributor Code of Conduct

    • Meetup schedules/events (cross-linked with homepage)

    • Mailing lists

    • Other communication channels

      • Stack Overflow

      • Twitter

      • GitHub

      • Slack

  • Blog

    • The blog will be edited via source control

    • Content from the Apache Airflow team

    • Articles from the community


  • Contribute (can be cross-linked to Documentation or Community).

Cover:

  • Comprehensive contributor guides

  • Ways to contribute

Include:

    • Start contributing

      • Repositories

      • Prerequisites/Contributor checklist

  • Downloads / Releases (cross-linked with Homepage download)

    • New version of the product

    • Features and improvements

      • Contributor recognition?


  • Site search - maybe

    • User is able to find content

      • Try to measure feasibility of Apache Airflow site searching capabilities

Footer

  • Communication channels

  • Sitemap




  • No labels