Design Contribution/Guidelines (DESIGN.md) Open Discussion

[una]

@lauweijie has a great idea for design documentation by pushing to standardize a DESIGN.md file.

The DESIGN.md file would include information pertaining to how to contribute design and project-specific guidelines for this contribution.

If we go this route, we can do this with the project board (check for the existence of a DESIGN.md file for admittance) to reinforce this pattern and ensure that there was thought behind including designers:

Cons to this approach are that it adds another dependency (this DESIGN.md file which isn't currently a standard) and it highlights a divide between design and development (an additional "special" requirement for design).

Some ideas include:

• separate DESIGN.md file
• DESIGN section within CONTRIBUTING.md
• Creating a CONTRIBUTING.md template with a DESIGN section as an example

There will likely be some kind of standard example or resource we'd want to provide

What are your thoughts?

[mrondina]

@una So, would the purpose of the design.md file be for the owner of a project to outline the design needs of his project? Or, would it be a guideline provided to designers to understand how to contribute to OS projects?

[una]

@mrondina it would be a general guidelines for designers to understand how they can participate and contribute. I think it would dually work as a means of getting the developers/maintainers to also think through their design needs and workflow. <-- this could change in the future though based on feedback and actual testing, but it's how I interpret it the design guidelines right now 😄

[GarthDB]

@una is right, github issues is the place to post design needs. Design needs are ever changing, but the way designers contribute should be standard (ish).

[mrondina]

@una Thanks for the clarification. I can see the benefit of having the guideline. Most of the discussion I think would be what is included. I also think that having a standard doesn't necessarily highlight a divide between design and development.

[simonv3]

I'd vote for including a section in Contributing.md

[RONNCC]

+1 I would love to know how to contribute for design like a CONTRIBUTING.md for code that lots of orgs have

[GarthDB]

What's the standard way we should use to specify the design section?

[simonv3]

How are we scoping design? Is it all of UX? Or is it specifically visual?

If the answer is UX, than I'm not sure we can categorize contributions that neatly. For example - is new developer onboarding part of UX?

What if we were cleverer, and looked for DESIGN.md, and if it doesn't exist, ask the user to highlight the relevant section in CONTRIBUTING.md? It's a bit of extra work, but maybe that's a way of tackling that? We could start a hint highlight at a header with design in it.

Alternatively, what if we asked the user to describe the design needs of the project, and we then did a PR to the project from within the app that creates a DESIGN.md file? Doing that smoothly would be pretty neat, and would go some way to creating the standard (and controlling the standard as well).

[jdittrich]

• File vs. Section: Adding a file (instead of merging a section into contributing) seems the be easier to handle (I like the process @simonv3 described in "… and we then did a PR to the project from within the app…")
• Naming: Should it not be Designing, so it matches contribut_ing_ and is not mistaken for design specs or the like?
• Scoping (@simonv3) This is a valid concern. I don’t have a clear cut solution but I would stick with "design" and leave it to the repos’s maintainers how they fill the term with meaning.

[pdurbin]

It is a great idea but can we back up for a minute and talk about the word "design"? Think about this quote:

"If you are an intermediate or senior developer, and want to see how your peers have solved hard design problems, these books can help you too."

Are they talking about the user interface for Firefox? The user experience of an open source app?

No! Well, not necessarily! The quote comes from The Architecture of Open Source Applications which covers projects such as...

• nginx
• Sendmail
• ZeroMQ
• CMake
• Riak

... and other quite low-level command-line only applications that have no graphical user interface.

Would a DESIGN.md file be appropriate for these projects? What about the design of a RESTful API? Would a file called UX.md be more appropriate?

[bnvk]

As per these points, it seems like cramming a bunch into one CONTRIBUTING.md file could get a bit overwhelming if you're not a designer / coder you'll have to weed through the "other type" outline. What names that pertain to who should read them:

• DESIGNERS.md
• PROGRAMERS.md

both of which are linked to from within the CONTRIBUTING.md which itself becomes more of document outing a few brief global contribution guidelines as well as a code of conduct and community policies!

[una]

@simonv3 what we were also considering is checking for a subhead of ## Design within CONTRIBUTING.md. Also, this design section doesn't really tackle the needs of the project -- just how to contribute design work and maybe some design-specific instruction. The needs would be within issues that get a label of design

@jdittrich interesting point about the naming. I like the ring of DESIGN.md more, but you're right about DESIGNING.md sounding more in line w/CONTRIBUTING.md.

@pdurbin I think a DESIGN.md file could surely be useful for any project. You give the example of a RESTful API -- sure most of that work is back-end, but there is always something that the user interfaces with (be it documentation, or even use cases, examples, etc.). Regardless, if the project owners feel like they don't need design help, they won't have a DESIGN.md file, in the same way that if they don't feel like they need any contribution help, they won't have a CONTRIBUTING.md. Also, to me, UX is a Design Discipline, so DESIGN.md makes more sense overall.

[simonv3]

@una If it's limited to instructions on contributing design, than to me it makes more sense to keep it in CONTRIBUTING.md. I realize that that is harder to look for, but it seems like if we're trying to make the barrier of entry easier, we shouldn't be splitting up where to look for how to contribute to a project.

If we're bringing Design out of Contributing, does that send a message that design is separate from contributing in a normal way? Aren't we trying to say that design is as necessary to a project's success. If we start breaking it out into its own file, are we saying to developers that design is a separate concern, and that it's Someone Else's Problem?

If we need a design.md file then I think, like @bnvk suggests, we'd also need a programmer.md file, and where does that end?

The problem is in part that there's no designers working on open source, but also that there's a cultural problem with developers working on open source who don't see the value of bringing designers on board, and equating their work to useful work. I'm not sure putting design.md outside of that consideration will help at all.

On the "what is Design anyway" note (@una ,@pdurbin, @jdittrich), I think that Design is a better encapsulating term for all types of design, which encapsulates information architecture, user experience, visual, etc. All of those disciplines are usually captured under a "designer" label on job applications, and I think that most programmers also realize the duality between Design and Designing an Architecture, and will recognize a "Design" label to encapsulate Visual, UX, IA, etc.

[GarthDB]

I really appreciate the discussion everyone. For now I think the consensus is to move forward with a #Design section in the CONTRIBUTING.md file.

I'm closing this issue, but feel free to make comments if you think we should open it again.