You
Thank you
No worries. This is just to say that the advice I will give is informed from my experiences working with these organizations and
Mostly within our team. So we are about eight nine people depending on how you count and we are dedicated to developing high quality robust easy to use maintainable open source software
For neuroscience and machine learning and
Collectively we build and maintain many projects. So we have about twenty five open source python packages. We mostly work with python
And that includes probably the most famous one is brain globe, which is a suite of tools for computational near anatomy
That has been cited hundreds of times. It has the millions of downloads 140 contribution GitHub and tens of packages that depend on it
So it is successfully adopted within the community, which is anish community but quite large
And we also have other projects. I will mention examples throughout the slides from brain globe
And also from another project which is much younger. It's called movement and it's the one whose development I lead
First of all, let me jump to the to the first of my three points, which is defining your mission and scope
And the picture I want to
You to imagine and that's why the animation is that open source software is a vast ecosystem
It's an interdependent network. It's a web of dependencies and relationships and competitions and collaborations
And when you start a new project your first job is pinpointing your location on this web
So you have to really drill down on the site where am I in the second system where does my project 15 within this larger image
And luckily as researchers you should be familiar with that because that's what we do when we start a new project
A scientific project we need to literature we identify the gap then we decide how we want to address the gap
And actually when you write the manuscript at the end of a project that's what you're asked to do right you write an abstract
And in an abstract you say this is the background this is the context that's the gap that's where my new piece fits in
And advice I really like in when doing science is that you should do an abstract not at the end but at the very beginning
So if you start to write an abstract before even start researching that has a lot of benefits
It's sharpens you're thinking about the project and then you're not really tied to it because it's not your destination
It's more like a compass so if you have an abstract in mind if you imagine the project finished and you kind of rework it as you go
It guides your decision making and it helps you not getting lost in this web of knowledge
So I want to bring this idea of abstracts from the scientific world to the software world
And in software we have no such thing as abstracts it's not formalized there is no structure
But if you look into the websites of your favorite software projects and the readme files you will start seeing some patterns that look something like abstracts
First of all you will often see a single high a single sentence high level description of the project which is kind of the mission statement
It's often what follows under the title or it sometimes it's in its own page. We will see examples of that and that mission statement is often followed by one of three elements
You often see specific aims listed under the mission you sometimes see the key features or the scope of the project and you also often see design principles or key architectural decisions
This is the front page of Bangalore, so the sentence of the top is to facilitate the development of interoperable Python based tools for computational environment
That's the mission statement and then you have a list of three aims which I will not read which are essentially you can think of it the same thing you would find in a scientific grant you high level mission and then key aims
Another project Python project I really like and userly often is Napaari which is a fantastic image here and this mission is a fast interactive year for multi-dimensional images in Python
And then you have four bullet points and those are the key features the key tasks that someone would use Napaari for and this kind of nicely defined the main scope of the project
When I started and my collaborators starting working movement we took this idea very seriously, so we did a lot of research
Literature research market research looking out what other tools are out there we talked to researchers who worked in the field
The relevant field field here is animal behavior actually and we kind of mapped out the tasks decided which tasks are difficult which tasks are already covered by existing tools and so on
And we came up with an abstract which you can read on our website
But then because I'm a visual thinker I thought okay, let's do it to one step further and let's make a graphical abstract
So this is our current graphical abstract which has also evolved over time as the project evolves
And here basically in this schematic you can see a summary of all the other projects that we interact with that are critical for us
For example the libraries we used to load the data from the library we used to represent the data and the one we used to visualize the data
And on the top you also see the key tasks or the scope of the project basically is for filtering visualizing and analyzing animal motion tracking data
So if you have the skills or if you have no someone who has the skills to do that I highly recommend a part from writing indexed your mission scope
Also making a schematic like that because it communicates kind of your your project's position in the web at the glance
And even people who are too bored to read the text can grasp the essence of the project
Making the abstract upfront has had many benefits for us and we do this now across our projects
One example I will bring up is that in the very early days of this project
Someone I didn't know, Mikael contacted us
And he wrote a message and he said basically hi, I follow the project from slides from the sidelines
I'm developing a similar packaging R, the functionality seems to overlap
Would be great to have someone to work together maybe we can have two packages one in our one python
And he nowadays is our most valued collaborator and we do actually what he suggested we are developing in parallel
We are coordinating and we are trying to serve both the art and the python ecosystem ecosystem for this task
But this would not have happened if we hadn't publicly and very early on stated what is our vision where we are going because
Doing that early allows you to invite scrutiny and collaboration early on
So basically if you do this at the beginning both the collaborators and the critics come early and that's good in both cases
The other thing I mentioned is that you sharpen your vision
So if you are forced to write down what your what your goal is in writing
One of two things happens either you realize the idea is done and you shouldn't do it because either it's already exists
It's served by another project or maybe you're not the right person to do it or two you really realize that the need is real
And you become capable of articulating the task
This allows you to convince your managers, your funders, your collaborators to advocate for the project
Because you've already sharpened your thinking about it
And the third benefit of having an abstract early is that in disagreements you have something to point
For example if you disagree with a collaborator on a technical decision for architecture or if you disagree on whether a feature is in scope or not
You can refer back to your written abstract and use that as a guide book as a constitution to help you make the decision
I will now move to the second part
So let's imagine you have written the abstract you know your vision you know where you're going
You're starting development and now you want to make your first release
The advice we hear often is really early really often and that's actually comes from the famous essay
The cathedral in the buzzer by Eric Raymond, which I highly recommend you read
Just a very one sentence recap of that essay
Raymond says that there are two models for software development that traditional model he calls the cathedral
Where you have a select group of craftsmen laboring hard for many many years to make this perfect artifact
This polish cathedral has no flaws and then reveal it to the world
The second model is the buzzer
The buzzer means embracing the colorful diversity and chaos of a buzzer
And in software terms it means that you welcome contributions from anyone in the world
It also means that you really believe that with enough eyeballs all bugs are shallow
And this is relevant to release is you release early and you release often
And that last advice is really the key one
In our team we have a particular recipe for what constitutes a good minimal viable product for a software
And that is a checklist of three points one
The software contains at least one useful feature
Basically it accomplishes one task its timelines exactly one task
Ideally exactly one that feature is well documented including user examples
And three the software install seamlessly on platforms that our target users may use
And I will unpack each of these briefly
One feature is really all you need
I really believe that because it keeps you focused on a concrete milestone
It protects you from scope creep
You might be afraid that people will perceive this as trivial if you come out and say
I can load CSV files
Big deal right that's not a danger because you have already articulated their mission in scope
So people can see the vision and can see how the first step fits into the larger vision
And the goal here is not to capture every possible potential user
But to capture at least a few early adopters
Because if you capture them early they can give you feedback at the most critical point where you can still easily steer the project
I really want to emphasize the point of seamless installation
And that's because I want to ask you how many times have you seen a software project online
Looks very cool you install it or you try to install it and you fail
How many times do you come back later and try again?
I suspect very very rarely
And that's because you don't get a second chance of making a first impression
So even if you're with your MVP with your first release which has only one feature
You have to try very very hard to make it easy to install
And I know it's hard and takes a lot of time
Because dependency hell is called that for a reason
But don't underestimate that amount of time that will take
Sometimes it takes more time than developing the feature
But it's important work if you want to come into adoption
And manage expectations upfront
So if you know your software does not run on macOS
Say it upfront on the homepage
So you don't disappoint people
For subsequent releases
It's basically the same as for the first release
You rinse and repeat
A few features at a time, ideally only one at a time
Avoid releasing undocumented features
And make sure you don't unknowingly break existing functionality
And small incremental releases are really powerful
And they rock basically and they benefit everyone involved
Because for your team it's easier to do cost correction
And you have a series of small wins that keeps them all high
For the users they can adapt their workflows gradually
And they want to be left high and dry when you decide to
One day write your entire API without warning them
And for the ecosystem especially this is really key
I mean you've all seen this graphic I'm sure
But the point of that is that
The ecosystem is a very complex independent structure
Your software is one piece I hope hopefully not this one
But maybe someone somewhere here
But if you move that piece very abruptly and very suddenly
Without warning the local structural collapse
If you do this often
People who start noticing and they will cut you out
Silently they will stop depending on you
They will stop using you
And then suddenly you will find yourself isolated
So be a good neighbor and be predictable
This brings me to my final point
Radically open communication
So both points I made so far the mission point and the releases
Our examples of one way communication from you and your team to the community
Now I want to talk about the communication
This more granular and multi way interaction
Basically I want to talk about where the day-to-day work happens
And how you align the interactions not only from you to the community
But also between the members of the community
So I will talk about in our team
How we handle how we approach issues, how we approach public requests
And other communication channels
First of all issues
We use them as a scratchpad
In our case it's GitHub issues but it doesn't matter
It can be GitHub, it can be any product management system
What I mean by scratchpad is that
If you get a new idea, write it down as an issue
If you get new information and existing idea, comment under the issue
If an idea grows and bursts its banks, breaking into smaller issues
If two ideas are related, cross-linked issues
And if the idea is no longer relevant, close-ish
That's the recipe
And it's all you need to do
But I really want to emphasize
You have to minimize the time between conceptualizing something
Addwriting it down
And my tip is if you can formulate as a sentence, it's right to be written down
Why do I keep insisting on this point as much as possible?
It's because it protects you from all kinds of harm
And it has many benefits
So writing things down keeps you from getting them
And I cannot tell you how many times I read an issue
I wrote a year ago, I had no memory of it
And I was very grateful that I had written it down
And I'm sure you had that experience as well
To you never run out of things to do
You have a very populated issue
So if you have some extra time on the weekend
And you look at this issue tracker
You have many tasks that are right to be picked up
And three, as I mentioned already, writing sharpens your thinking
But maybe you think, why do I have to do it publicly?
I can do this in a diary or in a logbook
I can really write it in a notebook
Why do I need to make this public?
I think the public is really key
Let's do another experiment
Let's see, you are using one of these two projects
And you find the back
And you go to the repository of the first one
Left and you see no issues, no pull requests
The other one you see
100 issues, 30 pull requests
Where would you post the bug report?
I think on the right
Why?
Because the live release tracker is a signal activity
It's also built trust
Because you can go read the existing issues
You can see how the maintenance is found
You can see the communication norms they follow
How they interact, how they react to bug reports
And that makes you much more likely to go and report something
Because you understand the social context
Without a population record, there is no social context
You are afraid, you don't know what to expect
Of course, the other benefit of a public scratchpad
Is that other people solve your problems
And this happens in real life
And it's fantastic when it happens
About pull requests, all I want to say is that
Please use them
So don't just push the main, even if you are the only developer
So if you are the only person working on the project
Still go through pull requests
Even though it may seem tedious
Again, there are many reasons for that
It leads by example
So if one day you say, I welcome contributions to pull requests
If there is a track record of your pull requests
You establish an example of how you expect this to be done
It creates a documented track record
So if someone one day you or someone else is debugging a project
Having that stream of well-described pull requests
It's really key to that debugging process
It facilitates review
And if you have at least one more person working with you on the project
We are blessed and please review each other's code
And remember that every code review is also an opportunity to enforce your norms
Because if you want to create a certain culture within the project
peer review is at least in their own days
Where that culture is born
Because how you review code, how you
The advice you give is really how you create the culture
So use it wisely
When your project grows, beyond the certain size
Issues and pull requests are no longer enough
That's because GitHub is mostly people like us and out there
Normal people don't hang out there
So you have to go where the community is
And for example in movement we also use Zuli
Passed chat platform as a forum
There are other solutions
But I recommend using something like that
To seek users' support to chat with each other
To connect with each other
The thing I want to emphasize here is that
Please minimize entry barriers
So don't use something that requires someone to send them
Email or get special access or permission from someone to be letting
Make it easy for people to come to you essentially
We also do community calls every two weeks
Where everyone is welcome to join
And we have social media channels
The word of caution here is that past a certain size
Managing all these channels requires significant effort
If you produce growth you will need a code of conduct
You probably need that from the very beginning
You will need governance structures
And one day you will also need the community manager
But if you reach that point
You have already succeeded at community adoption
And you don't need my advice
So congratulations
So a recap of all the points I mentioned
Three key takeaways
Write a software abstract
Because these curves out your place in the web consciously
And openly and from the outset
Relies are really often
Because the trust you build through incremental releases
Compounds over time
And it's worth far more than the polish you sacrifice
And the brace radical open communication
Basically write everything down
Maybe public by default
And let the magic happen
If you like this idea
I'm also writing them in a longer form than this talk
So I'm writing a block series
The first part which is about the software abstract idea
Is already out
And I will release the part two and part three in the next week
So check it out
Thanks a lot for your attention
And I'm very happy to take your questions
Thank you
Yeah, that's it
The question was how do we track the size of our user community
And how do we approach that?
That's a hard problem
It's a hard problem because we don't want to be invasive
We don't want to embed tracking and other stuff in our software
So it's hard
Long term you get a lot of
Because we write research software
Good signal with citations
Because people when they've cited
We know they use it
But this is this severely underestimated
The user community
Because most people don't
Don't cite it when they use it
And that's fine
This is a problem we encounter often when we have to write grants
And report to funders to advocate for more funding
And then we have to say how large is your community
The things I end up reporting is the size of the community
So on GitHub and on Zulip
Like how many people comment on issues and pull requests
How many people contribute?
Because for every person who opens a bug report on GitHub
There are probably hundreds more behind that person
Who have used it and have not opened an issue
And a thousand more maybe
So I know this also underestimates the size
But I don't have a good answer
Let me know
Yeah
Okay
We need a little discussion
Actually
Stins
Yes
Excuse me
Specific people in the book
Research software
How would you end up the scientific
Communication
Scientific science
That's
If you like with the amount of tuition papers
Yeah
So the question is
How do we handle the scientific communication side of research software
So do we publish papers to advertise our software or not
Sometimes we do
But our approach is we see scientific papers
Just as another advertisement vehicle
So basically
If we think the community we want to reach
We'll read paper more readily than they will read
An announcement on GitHub
We will write the paper
But we don't see papers as first class citizens
Luckily we are most of us are software engineers
So our promotion and our jobs are mostly
Just by software not by publication
So we don't feel obliged to publish to keep our jobs
Which is great
But we often do because we think that the users of the software
With the papers
And it's another kind of way to increase our visibility
But it's not a primary target
Yeah
My cell
When I do it can be programmed
Because I want to reproduce
We set papers
Yeah
So sometimes the papers we read
Could be either presenting the software itself
As a tool as a method
But sometimes it's in combination with like solving a scientific problem
And then by the way we saw to solve this we created this tool
And we have both types of papers
And in my experience people cite the papers
Scientists cite papers much rather than they cite
The UI of the software because that's what they are used to
So that's another way to kind of somehow track the usage
If you write the paper it's more likely to be cited
There are some solutions for that
Like jobs is a great initiative
The general of open software
Because it kind of hacks the problem
It allows you to have a sightable paper for a software artifact
And to an extent we also publish papers at jobs
Yeah
The question was if we have experience with lowering barriers for contributors
I mean a lot of the stuff I mentioned is going towards that direction
Already one barrier is people reaching you
And I showed like how you can lower that barrier of people reaching you
Finding you
The second is we run training workshops
We run hackathons
And last time we run a hackathon where we essentially combine workshops for users
And try to make them into contributors
So when we teach our workshop for users
We follow up with the hackathons
So that we take these users and
Walk them through the process of a git workflow
So it doesn't seem very very strange to them
And we try to also teach to our business students
Our postdocs teach the skills that they would need
So teach how to use GitHub and so on
But I don't have an amazing answer to that
Yeah
Thank you
We should wrap up
Okay, thank you very much
Thank you