Announcing The Swift Information Architecture Project

[James_Dempsey]

@carlynorama

Audience

Is this a good reflection of the audience breakdown?

• Newcomers to Swift
  • Potential Developers
    • advanced programmers
    • beginner programmers
  • Biz Dev (what is the business case for swift? Is this something to put on the site at all?)

I included just the sections that differ from the document. I think there is a difference between people who are brand new to programming, as opposed to experienced developers who are brand new to Swift.

I think in a number of ways getting an experienced developer interested in Swift overlaps a great deal with the business case. Although not present on the site at the moment, you could imagine success story case studies that essentially target both audiences.

@carlynorama

Specializations

All your specialization are technical. Is that on purpose? Was there any talk about framing them as industry specific?

At present, the list of specializations is not fully defined and examples mention are largely based on existing workgroups.

I think it's important to guard against having too many specializations which can make it difficult to build a community in each specialization. So, I think it may work best to start with a smaller number, which can grow over time as needed.

But, at a higher level, I think a part of the information architecture project it is important to define how a specialization is presented on Swift.org and the forums, so it can be replicated as new specialties are added.

[wes1 (Wes)]

@James_Dempsey

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

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

This makes sense, but leaves out evangelists and experts as a distinct category.

When I think about the broader ecosystem of Swift, I feel like swift.org has two main roles: friendly introductions to correctly orient the uninitiated, and a source of truth for experts. In both cases the goal is to enable them to do their own work.

There's a vast middle ground of discussion and elaboration for Swift developers that is simply too large for one site to fill, but I think that's best left to the broader community. To me swift.org should provide outsider Swift developers the initial launch vector and bounding guard rails. In both cases, the key is being definitive. swift.org should be the single source of truth for the broader community.

The role of (insider) contributors is a quite distinct category. Contributors need dedicated forums and git/PR/Issue/CI systems to hash out solutions not yet definitive, before the concepts, terminology and implementation has been set. It's a messy business, the history and details of which can be ... not illuminating, not definitive, and possibly misleading. The goal is to enable them to do the collaborative work of building swift.

It's very confusing for newbies or experts seeking definitive answers to stumble over the full history of contributor hashing (particularly when transported by search and AI agents across time and space).

The user profiles are quite distinct. Contributors are motivated, highly-technical, tolerant of ambiguity and eager to make a difference (have their say). Contributors can only really contribute if they can figure out how things work. They will get over most hurdles, and some technical hurdles ensure that contributors aren't taxing others too much. They can get information even through automation and API's. The actual number of qualified contributors is relatively small. So some technical challenges can serve as a selection filter. And their concerns are quite well represented here, and not likely to be missed.

By contrast, newbies and experts are in a way much less motivated. They need quick time-to-value. In both cases they're looking to be programmed: how does one do X in Swift? But they are the one who create value with Swift, and they are much, much more numerous. Reducing friction for them has benefits amplified by their number (and for experts, their number's number). Outsiders have been trained to quietly tolerate significant gaps as the price for working in such otherwise wonderful systems. All that means the cost to the community is both large and mostly unrepresented here.

I believe the SIAP first steps (principles or phase or ...) should be to segregate contributors and identify the deliverables needed for newbies and experts - their interface (content, form, and timing). Nicely, the chunks of work should be the same granularity, i.e., features in swift, (with some vision/overview/history context). This shared ontology should permit issue and workflow tracing, making it easy to identify gaps.

Contributors often have the best knowledge to write the definitive descriptions and to act as an expert. Training and promoting people as such would be great. But it's best for the community as a whole if others are also qualified and supported, because the gaps now are quite large, and contributors who have the bandwidth and skill to transition might be too few.

To stretch the analogy: if information architecture is flow of information, it should distinguish the intensely-interactive systems for production/contribution from the highly-scaled systems for publication/promotion, and not use leaks in the former to fix gaps in the latter.

I understand the SIAP is not charged with reshaping the community, but I do think it provides the mental model, ontology, and infrastructure that determines what needs doing. Using experts as a first-class user category should help hide some mess and fill some gaps

(Sorry I couldn't make this shorter.)

[James_Dempsey]

I don't know if you have seen the Swift High-Level Information Architecture document posted yesterday, but one of its goals is to segment the large information space into focus areas (contributors being one such area) so that project members with particular interest in each area can begin to work through the details.