website-revamp.md

Website Revamp

Status	In Progress
RFC #	#110
Author(s)	Aimee Ukasick (@aimeeu), Brian Le (@brian-armory), Rosalind Benoit (@dnilasor)
SIG / WG	Documentation SIG

Overview

Spinnaker.io is the public face of the Spinnaker project. This RFC proposes several improvements to .io and a pathway to achieving them.

Goals and Non-Goals

Goals

The ultimate goal is a more modern looking and consistently styled spinnaker.io.

To that end, these are the specific goals we are working toward:

• Provide clear entryways and paths for the different personas spinnaker.io should speak to; for example, a more clear and opinionated navigation for someone brand new to Spinnaker.
• Provide a clear and compelling answer to anyone asking, “Why Spinnaker for Continuous Delivery?”
• Add useful documentation features, e.g. versioned documentation and a better in-page table of contents
• Improve operator, end-user, and contributor experience by providing more navigable documentation as well as a search bar on the spinnaker.io landing page.
• Improve content organization to facilitate easy contribution.
• Improve local build time and adopt the new way GitHub pages uses themes
• Update and improve our ability to track and analyze Spinnaker.io visitor behavior

Non-Goals

• Not a complete reorganization of the documentation set. What will happen is the current documentation related tabs will be condensed under a single “Docs” tab in the top navigation.

Motivation and Rationale

Spinnaker.io has operated with one basic design look/feel since March 22, 2017. Given the current momentum and size of the project, it is time for a refresh. The Docs SIG feels it’s time to evolve .io beyond a documentation site and into a project hub, providing a presence for Spinnaker that is clearly segmented for different user personas.

We need to provide context to attract new companies and ICs as they encounter Spinnaker. This aligns with Travis Tomsu’s efforts to add more context and persuasive oomph to READMEs across the project. The window for Spinnaker inevitability is threatened by a crowded marketplace and will close; this project will boost Spinnaker’s profile and chances for inevitability. It will also integrate Spinnaker.io metrics into the CDF monitoring strategy.

From a technical standpoint, the way GitHub pages manages themes has changed to remote themes, and our implementation is outdated. Relying on the Minimal Mistakes theme-maintainer’s repository results in less theme-related maintenance for the Docs SIG and capture of theme feature improvements.

Timeline

• Achieve buy-in from stakeholders by March.
• Finalize Statement of Work and share with community in March.
• Obtain funding for a contractor from the Continuous Delivery Foundation after Statement of Work has been finalized.
• Finalize SIG-validated high-level design in April.
• Sitemap
• Accept contractor bids, including billing rate and time estimate, in April.
• Identify and hire webdev/design contractor in April-May.
• Work begins in May, validated with Docs SIG continuously.
• Work completed by July 1.

Design

Spinnaker Personas

• Individual Contributor: I am a developer who contributes code to the core Spinnaker project, or maintains a fork or custom extensions of Spinnaker for my company.
• Operator: I manage a Spinnaker installation for my company.
• App Developer: I am on an application team and use Spinnaker to manage my continuous delivery workflow as an end-user.
• Non-technical stakeholder/Executive: I am evaluating Spinnaker as a means to achieve some business objective.

Top Nav Menu

The current top nav will be condensed into 5 tabs:

• Getting Started
  • Basic conceptual info about Spinnaker for multiple personas.
  • Direct people to the next logical step for their persona
• Docs
  • All the current Spinnaker product documentation
• Community
  • Contributor Experience Resource, such as code and documentation contribution guide and contribution best practices and tips
  • Community Calendar
  • Usage stats
  • Governance & SIG info. This should be autogenerated from the Governance repo if possible. If not, we will continue to link to the Governance repo.
• News
  • Spinnaker newsletter
  • Featured videos
• Blog

Entrypoints & Tracks:

Check out the mock-up draft to visualize the proposed content.

Note: tracks overlap just as personas overlap for real individuals, based on roles and experience

• Executive track: Should answer "What does my life look like if my team(s) use Spinnaker?" for Executives

  • Card prompting clicks from those seeking to achieve business objectives, "Accelerate the velocity of your engineering teams"
    • leads to a persona-tailored content link in Getting Started
  • Case study content cards
  • Who should use Spinnaker card

• App Developer track: Should answer "What does my life look like if I use Spinnaker?" for AppDevs

  • Card prompting appdevs to, "Take your code from commit to production in one pipeline"
    • leads to a persona-tailored content link in Getting Started
    • Video carousel
    • Spinnaker Universe Calendar card
    • Slack join card

• Operator track: Should answer "What does my life look like if I use Spinnaker?" for Operators

  • Card prompting operators to, "Create and operationalize a golden path to production for AppDevs"
    • leads to a persona-tailored content link in Getting Started
    • Video carousel
    • Spinnaker Universe Calendar card
    • Slack join card

• Individual Contributor track: Should answer "What are my next steps?" for potential contributors

  • Contributor card
    • leads to Contributor section in the Community area
  • Spinnaker Universe Calendar card

Documentation Features

• Versioned documentation that corresponds to Spinnaker versions. This is a small widget in the top nav. See K8s docs for an example.

  • The version navigation widget will show the current version as default and include up to four previous versions.
  • We are currently working on a release handbook. Authors push PRs for new features to a dev-[future-release] branch. Authors push PRs addressing issues in the current documentation to master. So the PR process for most docs committers will not change.
  • Docs PRs would not be pushed to a previous release branch unless a code patch was cherry picked to a previous branch. In that case, the Docs PR would be pushed to master and cherry picked to the previous branch.

• Page-level table of contents that is always visible. This provides context and makes navigation within a page easier. See Istio docs for an example.

• Ability for reader to copy a code block with a click of a button

Analytics Improvements

• Event tracking in Spinnaker.io analytics using Google Tag Manager. This allows maintainers to gather data on link click and form submission events, for user activity monitoring and analysis.
• New Google Analytics property configuration to align with the CDF's strategy of consolidating metrics data collection across project web properties.

Drawbacks

Will cost money, and cost needs to be negotiated amongst stakeholders.

Prior Art and Alternatives

Prior Art

For design, Tensorflow does a very good job of creating clearly defined entryways for different roles. Additionally, other open source projects have implemented the documentation features we want.

Alternatives

• Do nothing
• Start completely over

Known Unknowns

What do people outside of the Docs SIG want to see in a new Spinnaker.io? What is the impact of Spinnaker.io on the contributor experience and Spinnaker adoption?

Security, Privacy & Compliance

We plan to display usage stats, as defined in Review of Project Telemetry Data Collection and Usage

Operations

Our goal at this phase is to deliver a refresh that will not introduce significant operational changes for spinnaker.io. This refresh shouldn’t change anything from a contributor’s perspective, other than file locations.

Risks

Should be minimal work, but unforeseen re-work could come up, expanding project scope. We could alienate the community with misaligned branding or documentation organization.

Future Possibilities

If we demonstrate that this refresh significantly increases traffic to spinnaker.io and supports Spinnaker success (i.e. increased traffic correlated with increased contributions/contributing company growth), we may later propose a more significant refresh. In doing so we’d like to avoid the K8S problem of having several contractors work on the site piecemeal, creating tech debt and knowledge scarcity. Our goal is to take a more pre-planned phased approach to improving the site.

Statement of Work

This work should be performed by contractors and/or Linux Foundation employees and supervised by the Documentation SIG.

Development

• Site architecture updates
  • Document site architecture
  • Replatform spinnaker.io from Jekyll to Hugo
  • Configure Netlify Build
  • Implement Docsy theme, and documented customizations as needed
  • Implement a widget to select documentation versions
  • Implement table-of-contents for each documentation page that stays visible as the page scrolls
• Home page updates
  • Implement homepage in alignment with design and mockups.
  • Enable card layout and update content block styling in theme
  • Implement new “companies using Spinnaker” logo area with all logos in community and success stories
    • Make logos clickable, linking to case study, testimonial, or video content
  • Implement youtube video carousel
  • Implement updated CDF-standard footer and push to a repo in the CDF org
  • Implement search bar on homepage using Algolia DocSearch for OSS projects
• Site content page updates
  • Convert raw HTML of Success Stories page so it can be updated using markdown and yaml
  • Implement videos area in Success Stories with a slider or grid that allows presentation of ~20 videos and links to the Spinnaker Youtube channel
    • Design should accommodate video categorization or incorporate Youtube playlists
  • Implement community calendar page linked to Google Calendar
  • Implement featured videos and featured tweets area in newsletter template
• Implement new functionality to enable readers to copy a code block with the click of a button

Web/CSS

• Create CSS theme(s) based on branding design
• Create CSS theme(s) (based on Spinnaker.io branding) for newsletter and success stories pages

Design

• Design updated sitewide branding elements that leverage existing logos and colors to provide a consistent brand image across content pages
• Design replacement for large projecting sail motif, which is difficult to style content around, with a more compact defined
• Design home page hero graphic
• Design new newsletter signup forms for homepage and news area
• Design editions list page and newsletter edition theme
• Design new Success Stories pages that break up content into case studies, testimonials, and videos
• Design attractive success stories index page that serves as a “features” area for featured case studies, videos, etc and links to subnav content
• Design community calendar page

Documentation SIG Scope of Work

Some of the proposed changes are out-of-scope for this SOW. The Spinnaker Documentation SIG has committed to performing work on the Spinnaker.io refresh including but not limited to:

• Creating site map
• Creating basic site mockups to illustrate requests
• Writing copy & content
• Sourcing graphics for card icons
• Implementing new site navigation
• Consulting with private contractors on design decisions and implementation details
• Collaborating with and supervising contractors