Announcing The Swift Information Architecture Project

Swift Website
1

On behalf of the Swift Website Workgroup, I'm excited to announce the Swift Information Architecture Project!

This project aims to design and implement a unified information architecture for content across the Swift project, including the content on Swift.org.

We believe the best way of achieving this is by including the Swift community in the process and invite you to read the project brief below to learn more about the project and how you can participate.

:information_source: This project runs in parallel with the Swift.org Redesign Project which aims to modernize the website's appearance, enhance user experience, and better support the evolving needs of our community. This project is also inviting the Swift community to participate.

Swift Information Architecture Project

Overview

Over the past ten years, the Swift project has grown from a handful of GitHub repositories to a large number of projects, including the Swift.org website. Over that time there has been no unified information architecture—content and its organization has developed organically. This project aims to define underlying principles for information architecture and then apply those principles to existing and future content across all of the sites of the Swift project.

At a high level the development of the information architecture will have three phases:

  1. Develop underlying principles for the architecture
  2. Design architecture for existing pages and content according to the principles
  3. Plan and implement architecture across existing pages and content

All architecture documents will be made available in the Swift forums for community review and feedback.

Principles

  • Organization-wide Architecture
    The Swift project provides information in a variety of ways including Swift.org pages, DocC-generated documentation, GitHub repositories, and more. The information architecture needs to span all of these to provide a cohesive strategy for the entire project.
  • Best Suited Site
    Information will be presented where it is best suited for the content and audience. For example, GitHub is well suited to host content about contributing to swiftlang projects, whereas Swift.org is well suited for content aimed at newcomers and users of the Swift language.
  • Single Source of Truth
    The project should strive to have a single source of truth for a topic across all official Swift project sites.
  • Progressive Disclosure
    Information should be presented as a high level summary first with the ability to drill down into increasing detail and specificity.
  • Data-driven
    Where possible, presented information should be data-driven via json or yml files or other files with structured data.
  • Funnels / Slippery Slopes
    Where appropriate, content should present encouragement and next steps focusing on leading visitors towards:
    • Further Learning
    • Community Engagement
    • Contributing

Sites / Information Sources

In addition to Swift.org, the Swift project has a number of online sources of information and community interaction:

There are also sources of information that are outside the direct control of the Swift project that need to be taken into account:

Part of the information architecture of the project is a clear definition and rationale of which content belongs on which site. Or more colloquially stated as "a place for everything and everything in its place".

Audience

There are many ways and levels of granularity that the audience of the sites can be categorized.

At a high-level the audience falls into three categories:

  1. Newcomers
  2. Swift Developers
  3. Contributors
    a. Potential Contributors

Each section and page on Swift.org should have a specific audience in mind. A page or piece of content may be useful to more than one audience, but the content and tone should be geared towards the primary audience.

The 'Potential Contributors' audience is a case where pages or content that are primarily focused on another audience may have this as a secondary or tertiary audience in the form of an encouragement or call to action to contribute.

Use Cases / Specialties

In addition to audiences as mentioned above, another way to categorize the audience is by use case or specialty. This is an area that could potentially lead to a significant expansion of Swift.org, for example providing specific landing pages focused on use cases such as server-side Swift or embedded Swift.

Current use cases beyond Apple platform app development include:

  • Swift on Server
  • Embedded Swift
  • C++ Interoperability
  • Platform-specific / Linux / Windows

Summary

These are the main principles, sites and audience segments that will inform the information architecture.

Current Site Examples That Violate Proposed Principles

This section contains some examples demonstrating issues with the current information architecture of the project. They are small case studies of how information on the site has grown organically without an overall strategy and provide motivation for a unified information architecture.

"Slippery Slope" Example

The diagram below depicts the current state of trying to get from the Contributing item on the main page of swift.org to the Getting Started directions of contributing to the swiftlang/swift project.

At present, the site is a tangle of links and backlinks with only one path that actually brings the visitor to steps to get started contributing.

The path should be much more clear and direct.

Flow chart showing path from Swift.org to Getting Started Guide on swiftlang/swift
Flow chart showing path from Swift.org to Getting Started Guide on swiftlang/swift2138×1052 148 KB

Single Source of Truth Example

The Swift Package Manager currently has at least four different sources of documentation.

This makes it difficult for newcomers and developers to find all the relevant documentation for Swift packages and make it likely that one part of the documentation or another will become out of date.

There is the overview and tutorial on Swift.org:
Swift.org - Package Manager

The markdown documentation in swiftlang/swift-package-mananger:
https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/README.md

The DocC generated content hosted on docs.swift.org;
PackageDescription API — Swift Package Manager

And finally documentation on developer.apple.com:
Swift packages | Apple Developer Documentation
PackageDescription | Apple Developer Documentation

There is likely to be some duplication between the Swift project and developer.apple.com. But otherwise, cases like this should move towards a single source of truth.

Next Steps

The goal of this document is to articulate the underlying principles of the information architecture.

The intent is that the underlying principles provide guidance moving forward as new types of content may need to be added to the information architecture.

The next step is to solicit and incorporate feedback from a wider audience, including the website, contributor experience, and documentation workgroups to get agreement on the principles.

The final step is methodically going through existing content and making and implementing plans for each section.

Technical Requirements

The project has no specific technical requirements. The design will take the capabilities and limitations of each site / information source into account.

Project Timeline

The timeline of the project reflects its comprehensive scope beginning with principles, progressing to design and culminating in detailed changes to implement the architecture.

Phase 1: Develop Core Principles

  • Develop a set of core principles to guide the information architecture design.
  • Review and refine principles based on stakeholder and community feedback.
  • Form working groups of stakeholders to focus on applying principles to different areas.
  • Deliverable: A principles document to guide further design efforts.

Phase 2: High Level Architecture

  • Develop the high level information architecture.
  • Conduct a review of existing information architecture.
  • Focus on how information will be provided across different project sites.
  • Review and refine based on stakeholder and community feedback.
  • Deliverable: A high level architecture document to guide detailed design efforts.

Phase 3: Audience / Area Level Architecture

  • Working groups develop architecture for each audience / area.
  • Review and refine based on stakeholder and community feedback.
  • Deliverable: An architecture document for each audience/area.

Phase 4: Detailed Plans and Implementation

  • Create detailed plans and file issues for required changes to implement plan.
  • Begin implementation of changes.
  • Deliverables Detailed issues filed to implement architecture.

Phase 5: Remaining Implementation

  • Continue implementation of issues.
  • Identify and work to address any implementation blockers.
  • Deliverable Completed implementation of unified information architecture.

Roles and Responsibilities

Project Team

  • Dave Verwer (Swift Website and Documentation workgroups)
  • David Rönnqvist (Documentation workgroup)
  • Dianna Ma (Documentation and Server workgroups)
  • James Dempsey (DRI)
  • Joe Heck (Contributor Experience and Documentation workgroups)
  • Paris Pittman(Core Team)

Stakeholders

  • Swift Website Workgroup
  • Contributor Experience Workgroup
  • Documentation Workgroup
  • Swift Core Team
  • Apple
  • Swift community

Community Participation

Participation in the Swift Information Architecture project is open to all members of the Swift community.

There are a variety of ways to get involved:

Join project and working group meetings and discussions

The core effort of the project will be working through the information architecture for different areas of focus. This will happen through small working groups collaborating on the design for each area through meetings and discussions. Please send a message to @swift-website-workgroup on the Swift forums to join this effort.

Review and provide feedback on design plans and proposals

Once an initial design is created, it will be posted in the Swift Website category on the Swift forums for review and feedback. Turning on the ‘Watching First Post’ notification of the Swift Website category in the Swift forums will notify you when any new Swift Website thread appears, including review threads for this project.

Working on issues to implement the design

As information architecture designs are finalized, GitHub issues will be created for the concrete changes required to implement the design. These issues will be found on the Github project page for this project. Contributing pull requests that resolve these issues will help move the architecture from plan to reality.

Throughout the process, the current status of the project will be available on GitHub.

37 Likes
2

Very happy to see this initiative together with the redesign one, nice!

There is a single thing I especially would want to call out that would be extremely valuable:

Some mechanism for linking out from the documentation to the evolution proposals.

The evolution proposals holds a treasure trove of information, and it seems unlikely all of the can be fully integrated into TSPL.

I don’t know the answer on how to do that - but it’d be useful for many I think.

Don’t know if it is in scope for this project, but wanted to call it out.

10 Likes
3

Good work.

I feel especially excited about incoming improvements related to the "Single Source of Truth" part. I believe It will benefit the community greatly and make Swift more approachable.

3 Likes
4

For documentation with inline markup, XML is much better suited and therefore "more universal" than JSON or YAML (YML) from a practical standpoint. For technical documentation you should not use JSON.

2 Likes
5

Thank you for the feedback. I also have found that evolution proposals typically provide the most detailed documentation on their respective topics.

If you have further thoughts about how to best integrate these links, please pass your thoughts and suggestions along.

2 Likes
6

Thank you for pointing that out.

Specifically calling out json and yml was mainly because those formats are already being used as data sources for the evolution dashboard and generation of static pages.

As the project progresses, we will be open to discussing whichever format will be most suitable for a particular use case.

1 Like
7

One possibility would be to integrate something like this into TSPL and other relevant places (this is an example from archery but the structure is relevant):

https://www.worldarchery.sport/rulebook/article/3138

Scroll down a little bit to ”Nocking Point interpretation” or ” Use of visual and audible clicker interpretation” which provides some very specific technical details as well as a link out to the full ruling of the technical committee.

For swift, this could be a short text if relevant and a link out to the evolution proposal (or relevant anchor in a proposal).

1 Like
8

Yes, possibly at the end of a section or article there could be a small "Related Evolution Proposals" callout with links to the relevant proposals for that topic.

Some language features, generics for example, have gradually evolved over the course of a dozen or more proposals. Simply providing a dozen links might be overwhelming. It may be that some sort of index page that provides a brief synopsis of each proposal might work.

Also, I would encourage you to be involved with the project, either as a more formal member, attending meetings, etc. or as you are doing now, providing feedback to proposals as the project team develops and releases them.

1 Like
9

This is great to see. My confidence in Swift stems in part from seeing it always maturing.

Goals, principles, and methods focus efforts, so it might help to remember some perhaps secondary goals/issues as you factor efforts.

(Should this be discussed in this thread? on project pages?)

My impression is that it's hard to get information from those who know to users. Some of it leaks in forum discussions, but the docs seem to have the bare minimum (likely due to hardening required for such a large audience). One goal could be to make it trivial for people in the ordinary course of work or discussion to contribute stuff back into the communications channel, to improve productivity-availability-coverage. (But then how does it get polished for users?...)

A "single source of truth" does ensure no inconsistency and, when coupled with effective distribution, more efficiency. But it might not be optimal to have only one distribution point for a piece of information. Users come in many forms from all directions with unique issues. Engaging them entails significant variety, and navigating between points entails some ontology. Similarly, aiming to "Put everything in its place" can devolve collaboration into turf battles. An alternate goal could be for different users to always find what they're looking for (and "places" to map to user profiles). Both suggest a production model, with single validated sources delivered to multiple sinks via automation/linking.

Perhaps commented sample code could be the lingua franca for contributions (and datum/node for information). Running code that makes sense is helpful standalone, and it can be incorporated into larger discussions, docs, or pages, automatically after curating with ontology tags and for deep linking. Once validated and integrated, samples could be maintained entirely by the community, since they require only Swift skills (and the compiler and ontology-linking tools would provide integration checks). Beyond language usage/docs, open CI scripts for each environment variant would be examples for install/deploy issues, and the standalone sample code contribution conventions could be adopted to get runnable compiler bug submissions for automating triage. Sample code would play to the strengths of producers, maintainers, and users, and would leverage automation. A sample code library could support multiple generations of site/forum design or information architectures, and be helpful standalone.

1 Like
10

Hi, I see a missing lens on this proposal and that is auditing what are the pages that get the most traffic from SEO or other channels and how can they be optimized and emphasized. What other topics that could be driving more SEO traffic and need to be shored up? For me SEO is a very large consideration when redoing information architecture. Additionally there is usually a competitor analysis part of an IA project as well which should be a useful exercise.

Would be interested in contributing to this part of the project. Will follow up.

11

i’ve said this before, but it will just need to be repeated until action is taken: we need to upgrade the community’s Slack plan so that the workspace retains content beyond the 90 day expiration window in effect under the free plan.

quite literally every day we lose valuable information, which often cannot be found anywhere else (without bothering a compiler or package maintainer), because it lapses from the Swift Slack workspace.

12

As someone who runs multiple online communities for various topics, I would strongly recommend against using Slack. Yes it has a decent UI, but it has very very very little in the way of moderation options. It is also absurdly expensive for running a community.

I would suggest that, if this is a priority for the group, we should be looking at Discord. It doesn't have as nice of a UI and the threading is weird, but it is far more customizable.

2 Likes
13

the problem is we have tried migrating the community to Discord, multiple times if i remember correctly, and it has never gained traction, i imagine due to Slack’s central positioning (and i suppose, branding) as the the platform for “professional” collaboration.

so i feel like, having attempted such a transition before, we may need to just accept that we are tied to the Slack platform, like so many other organizations are.

14

This is getting off topic of discussing the Information Architecture Project itself.

This would be a great discussion though for a separate thread focused on this issue.

15

Thank you for your feedback and thoughts on the project brief.

I think your post contains two interrelated topics.

The first being the information architecture with a goal of bringing a deliberate design to the large amount of information already present across the entire swiftlang project, with a mind towards extending that design over time.

The second being the documentation process itself—how best to capture information and present it to users.

This project is focused on the first but improving the documentation process is definitely important as well.

Yes, the "single source of truth" refers to having a single source for information, but that information could be presented in multiple places.

The principle is mainly to guard against things such as the project having three different introductions to the Swift Package Manager that need to be maintained, each presenting a slightly different subset of introductory topics, for example.

Or multiple versions of contribution guidelines for the same repository, again, each with slight differences.

Yes, I think any time there are different groups of people collaborating that turf battles need to be guarded against. So far, in my experiences with the various Swift workgroups and steering groups, I have found a high level of healthy collaboration.

One of the reasons for having this project be an open collaboration with members of relevant workgroups and interested community members is to have a designed architecture with well-documented rationale.

Yes, definitely with the potential to present the validated content in multiple places / contexts.

I've thought about something like this also. Swift Package Manager has implemented a feature called "Snippets" which is essentially small snippets of sample code that can be compiled.

These would likely be the starting point for something along the lines of what you suggest.

I think that does fall into the realm of improving the documentation process and working out the details is beyond the scope of the information architecture project.

I believe the information architecture project is a significant undertaking and when it is complete, should improve finding and navigating information across the swiftlang project.

However, I also see the end of the information architecture project as the beginning of building upon the the design to make additional improvements and adjustments in the future.

1 Like