Idea to make design a bigger part of open source projects

Hello o/

I’ve been thinking about how to organize and communicate design with developers on FOSS projects. I’ve found something and I’m starting to use it myself on my projects.

The idea would be to include design documents directly into the git repo of the projects as markdown files, such as in a “design” directory at the root of the project.

Having all of the design directly in the repository also makes a kind of “statement” saying that design is just as important in the project as the code itself. As well as making easier for developers to access and participate in the design.

Within that “design” directory, it could be divided into 5 subdirectories for each part of the design process

  • empathy or research directory: Contains everything related to the research made to understand the users’ needs.
    • Example: user interview questions, user interview notes/transcript, links to interesting UX research, other notes, survey responses, etc.
  • define directory: Contains everything related to the definition of the project’s scope
    • Example: epics/user stories (list of features), personas, etc.
  • ideate directory: Contains things related to exploration, any all the ideas that came up for the project
    • Example: mood board, inspiration board, brainstorming session notes, etc
  • prototype directory: Contains everything related to the creation of prototypes of the UI
    • Example: used design system, component library used, existing prototypes (Figma, Penpot), screenshots, etc
  • testing directory: Contains everything related to the testing of the prototypes both by users and by developers/designers
    • Example: checklist (such as accessibility checklist), description of user testing scenarios and results (like list of tasks, evaluated axis, results, conclusions, heatmap), A/B testing, etc.

I know that this division by steps and what each of the steps are can be controversial (and that design is not linear), but I find it interesting nonetheless because it places the users’ needs as key factor and makes it easier to understand how the design process works in general.

Of course I’m also very much a beginner, so I would love to hear your thoughts on this.

5 Likes

You got some very interesting ideas here! Do you have ideas on how to implement this?

1 Like

Thanks a lot for the positive feedback :)) Technically speaking, in term of implementation it simply is markdown files in a git repository so there’s not really anything to develop :stuck_out_tongue:

I don’t know if you’re familiar with Git or things like GitHub, Gitlab or Forgejo but usually you can simply go on the project, create a file like user-testing.md and start writing using their editor :slight_smile:

My idea is simply a form of structure of that content, but there’s already some people sharing this kind of things, the main one I can think of is the Forgejo project which has quite a lot of user testing and user interviews notes such as on this repository

I’m also trying this structure myself in one of my project (hasn’t really started the code phase yet, still looking around in design research though), you can find it on my repository here.

Note things are very minimal given I don’t have much time to work on that project at the moment :sweat_smile:

1 Like

Interesting structure. The part that caught my attention the most in your repository were the “personas” and “user-stories” files in the “define” folder. I’ll definitely think about ways to add this concept to a project of mine.

1 Like

First, I applaud your desire to help here and I’d like to be of help (and support) to you. I’ve worked on a few things like this myself in the past. What seems most helpful is go give a checklist (or template) and let people pick what they want to do. So if they don’t have any research but have a clear target user and a problem statement, they could fill those out. This doesn’t excuse the lack of research, only that you get people on board by writing up what they have.

I’ve started similar project “the GIST checklist” which is checklist of things to write down whenever you are considering a non-tribial change to your project. It’s meant to be.a way to get everything critical into a single place so people can discuss and.figure out what to do. It’s solving a different level of problem from yours but I do think we’re both trying to help in related ways. Here is the link: The GIST Checklist - Google Docs

Happy to keep discussing how best to do this.

2 Likes

Research is very doable to include as markdown but it’s hard to do pretty much any visual image artifacts due to the nature of git and how it stores files.

If you want to see a way you can organize research check out this thing I made: GitHub - jcklpe/research-ops-hackpack: Template repo for bootstrapping a researchOps practice using github.

1 Like

Hello, I like how you try to include design and designer in the dev world. :slight_smile:

my two cents:

  • how do you handle binary file such as .jpg, .psd, .doc, .blend etc… ? because the space needed could be huge!
  • markdown is perfect for text but not for graphism, how do you think designer will adopt that limitation?
  • actually git itself is very special, do you think that ‘not software developer’ will use this kind of tool?
  • there is tools like penpot that try to be for designer and devs. Is your idea in competition with or is it a complementary tool?
1 Like

In fact, I’ve seen more than once people using git to create collaborative literary texts (kind of like a shared document).

2 Likes

My two cents on the topic, to provide my idea of how it could work with the current repository rules we follow on GitHub - xwiki/xwiki-platform: The XWiki platform . Only committers are allowed to push/merge onto the master branch of the main fork. Everyone else goes through a pull-request that must be validated and merged by a committer. Committers are important members of the community that know, understand and respect our code quality practices (among more expectations…). The definition of committership in our community.

If we wanted to add some prototyping data to our codebase, it would mean that:

  • We create a lot of pull requests, it takes time from committers to review them, and probably at least some of them get forgotten / merged late. Currently, it takes most of the time a couple days for committers to review PRs, which is already good given that a PR can be opened at any time. It’s a heavy process that I don’t think works so well with any tasks that requires frequent updates.

OR

  • We update our project governance to go around the issue above. But this update will surely need to compromise on code quality or security.

Right now, we use a wiki to store design research and prototypes. We usually link it together with our ticketing tool. It’s not perfect but it works pretty well to organize and communicate design with devs in our community.

TLDR: The idea described does not work so well with every project, depending on their project governance. Described an alternative solution that does not use the main codebase to store design research.


Thanks for sharing your idea!
Lucas C.

Sorry I kind of forgot to check my messages ^^’

Thank you <3 I find your GIST checklist pretty cool too, I’ll keep it in mind :stuck_out_tongue:

I forgot about this annoying thing with the git storage of images. It’s true that given this, having something other than git could be a good idea. But I remain convinced that markdown and git could be a great way to store files for both devs and designers and is a lot more accessible, light and universal than stuff like custom forums, pdfs, or MS Word documents.

This project is by no way a competition to penpot. Penpot is an amazing tool (though I don’t use it much because I prefer prototyping with code itself), this project is more of a way to organize, share and structure design documents, and for instnace the “prototyping” directory could very well contain links (or files) to penpot projects.

First off, I find that the wiki you shared which I explored for a bit, with usability testing, prototypes, etc is extremely cool and is exactly what I want to see more of in open source and free software. You also made me discover XWiki which seems pretty cool as well, I had never heard of it before.

Of course making things in markdown on git is just a proposal, but in existing projects where it might not be possible, it’s not so bad, just having this publicly somewhere is already extremely cool.

The only thing I regret with it (having it in forums or external tools) is that they are often hidden and honestly this type of stuff deserves more visibility (for me personally it’s even a selling point for a project to know that the people behind the project has done such great research).

Also, in many cases the design revolves around things like forum, which I find quite sad because it’s really hard for newcomers to get in and be able to have an overview of the work that has been done because everything is buried in a long loosely-organized list of discussion threads.

1 Like