Create a new design document index and process

[parlough]

I've been seeing a few mentions for increased visibility and discovery of design documents as Flutter developers want to better understand areas being explored or provide their own feedback.

We have https://docs.flutter.dev/resources/design-docs but that is just an alphabetically ordered list with little value.

Could we introduce a process of not only adding a redirect, but perhaps adding to a YAML file with the go link, a short description, author, product/focus area, date, etc. Then we can render that information with more information that is ordered, categorized, searchable, etc. This file could be added to in the same PR as when the redirect is added.

- title: Flutter blank canvas custom controls
  id: blankcanvas
  description: > 
    Lower the cost for people to create high-quality bespoke widget sets, 
    whether to better fit their brand identity, 
    further differentiate themselves from competing apps, 
    or just to add whimsy.
  authors:
    - Hixie
  date: 2022-11-18
  areas:
    - framework
    - widgets
    - api

Questions: Do you think this would be valuable? Worth the little extra work? What information do you think would be useful to include?

[parlough]

\cc @Hixie In case you've considered this before or have thoughts?

[sfshaza2]

Yes, I think this would be valuable. I just want to make sure that we aren't then tasked with keeping such design docs up to date.

[Hixie]

We were just discussing this at the openness meeting on Tuesday. @itsjustkevin and I are debating whether to use GitHub or Discord to manage it.

[sfshaza2]

Does Discord provide a way to manage projects?

My vote would be to use GitHub.

On Sat, May 27, 2023 at 2:56 PM Ian Hickson @.***> wrote:

We were just discussing this at the openness meeting on Tuesday. @itsjustkevin https://github.com/itsjustkevin and I are debating whether to use GitHub or Discord to manage it.

— Reply to this email directly, view it on GitHub https://github.com/flutter/website/issues/8749#issuecomment-1565701876, or unsubscribe https://github.com/notifications/unsubscribe-auth/AKS4PKJTGSE6G6TBL6CJAS3XIJ2A3ANCNFSM6AAAAAAYOFRZHQ . You are receiving this because you commented.Message ID: @.***>

[Hixie]

Can you elaborate on "manage projects"?

[sfshaza2]

@Hixie, maybe I'm conflating things, but @itsjustkevin has been looking at GitHub projects to manage release work. Since most (all?) of Flutter/Dart DevRel folk use GitHub as part of our daily work, I just prefer to use GitHub.

[Hixie]

The whole team should be using Discord as well. That's our official intra-team communication channel. :-)

I'm not sure there's any projects to manage as far as the design docs go. It's mostly just a matter of having somewhere to list the docs under active discussion. We're currently studying whether we can use GitHub for this but the main sticking point seems to be that non-team-members aren't able to do things like add labels or (if we use a project or some such to list the docs) move them around a project. On the other hand on Discord we would be able to give anyone the ability to move things around and label them and so on but the search/archiving experience is not as great.

[itsjustkevin]

@parlough I would like to propose that we remove the page entirely.

I am not entirely sure that we want to post design documents on the website while authors are working through their ideas. This may be a factor in keeping people who are a bit more reluctant to have their work so easily searchable and indexable.

Removing the page and bringing the design documents to github could remove website maintenance and drive traffic back to the flutter/flutter repository.

What are your thoughts?

[parlough]

Edit: I see now after the later clarifications, removing it in favor of a still-open GitHub tracking system (or similar). Any way for developers to have more insight into current designs sounds good for me, so I'd be happy to remove it or redirect to that list! :D

---

My understanding is the point of adding a /go/ link to a design doc is to gather feedback on it. It seems Flutter developers want more and deeper insight (and perhaps input) into the designs going on, not less. This is sort of similar to RFC systems by other communities (https://github.com/rust-lang/rfcs). If developers are still working through their idea and not ready to share it or for feedback, I'm not sure they should add a go link.

~I feel removing the page would make the design and planning process even more opaque than it already is.~

[sfshaza2]

Interesting thought, @itsjustkevin. But, yeah, these go links were specifically added (originally by @Hixie) in order to gather feedback. Now, I believe that his intentions were that these would be temporarily available, but we've never removed these links. @Hixie, can you weigh in?

[Hixie]

@itsjustkevin and I are working on a plan to have GitHub issues track currently open design docs, at which point I think this page becomes mostly moot as a way to get feedback — we would just point people to the GitHub list. I think keeping the URLs working long-term is valuable (URLs should be stable and so on), but yeah, I don't think there's much point in having a long list of mostly-obsolete design docs around, especially without context. (Also, as the web site is user-facing and these are contributor-facing docs, it's a bit confusing to have this list on the web site.)

[parlough]

I see, thanks for the clarification!

If there will be a GitHub (or other) system to track designs looking for feedback, that's great and I think we could happily drop this page, or redirect it to that list (or details about it) :)

[parlough]

I wonder if GitHub discussions with a custom "Design" category would be a good choice? That way there is a dedicated space that won't get mixed with the huge set of issues, while still supporting some filtering and labeling.