Public Lab Research note


Draft of a Public Lab Software Roadmap: Comments welcome!

by warren | May 22, 2019 19:46 22 May 19:46 | #19494 | #19494

Hi, all - we've been working on this idea for a "Roadmap for Public Lab code projects", as part of our goal to improve transparency, discussion, and the sharing of decision-making in the Public Lab code community. We on the Public Lab staff, and people who've been very involved in PL, use a few different venues to discuss/plan/chart our work, including:

(Above draft diagram from our Mockups document, NOTE: updated diagram below)

Update: software overview: we've just (as of Nov 2020) published a new Software Overview page with a detailed description of all our software projects, who uses them, goals and how they interconnect. Take a look!

A roadmap can provide an overall trajectory -- not to replace the above processes, but to link them together into a coherent direction that helps community members stay synchronized and play a larger role in planning out new features, implementing them, and ensuring that activity across the code community matches our community-wide priorities and the mission of our organization.

In this roadmap, I've tried to highlight one specific major change in direction, which is the shift towards a more stable core codebase at PublicLab.org, while providing a framework and support for "satellite projects" which are more ambitious and exploratory to happen in a modular way -- much as the Editor project, Leaflet Environmental Layers, Image Sequencer, and others have done. Our hope is that this can provide a more consistent and stable experience for site users, while leaving plenty of opportunities for interesting and innovative projects for our coding community.

Here's the draft:


Roadmap

The Public Lab Software Roadmap will help us build shared goals around software development, especially for the plots2 codebase, but also for how we plan/start/build/maintain and even gracefully abandon coding projects at Public Lab.

Goals:

  1. A more stable PublicLab.org experience whose core functions are consistent and error-free
  2. An easier to maintain site that has fewer and fewer bugs
  3. New features when appropriate
  4. Interesting new projects for people to work on & space to prototype really great ideas that will make the site better
  5. Useful tools of all kinds for people across the PL network

Problems:

  1. People making new features could use more help understanding how they fit into the big picture and what purpose they serve in the broader Public Lab community
  2. New features can sometimes disrupt basic site functions - by generating new code
  3. Continuous change can be good (site improvements) but also an issue if people constantly have to re-learn core systems

Ideas:

  1. This Roadmap, to help us coordinate
  2. More and better tests to stabilize our code
  3. Deprecating old code and aiming for a simpler, less complex core codebase
  4. Style Guides (both the visual style guide here and a code style guide!)
  5. Spinning out stand-alone "satellite projects" that run on minimal infrastructure (mostly in JavaScript) that can be installed as "modules" on the site, rather than add to the codebase complexity: like the Editor project, Leaflet Environmental Layers, Image Sequencer, and others
  6. Allow/encourage rewrites of site functions... (like in React, which was a popular idea this year)... only? ...if they come with good tests (end-to-end system tests?)
  7. Identify and rally contributors towards "big projects" (milestones?) and "priority fixes + features" (the "priority" label) we're trying to complete and recruit help on (rather than starting new projects? or, at least higher priority than?) to start to complete them and reduce our "technical debt" (is this a good frame? https://en.wikipedia.org/wiki/Technical_debt)
  8. Encourage ppl to choose a segment of the code to specialize in (add your name to a group?) to build longer-term institutional memory and capacity to maintain the codebase (not sure about this one? Would love input!)

Roadmaps are a great way to set a trajectory for a community. Here's a great example from the p5js community: https://github.com/processing/p5.js/blob/master/developer_docs/roadmap.md

Overall project goals

A clear and specific definition of what we want our website to do (especially what no other platform provides) helps everyone distinguish between "core" functions and "satellite functions," freeing us up to prototype, explore, and innovate in satellite functions, while prioritizing stability in core functions.

So, let's try to describe what makes our platform unique, and what it's core functions are!

Part of this is gotten at in this section of our main README file:

https://github.com/publiclab/plots2/#what-makes-this-project-different

The people who create our platform make very different design and technology decisions from other projects, and this stems from our deep belief that, to see a change in the world, we must build and maintain systems that reflect our values and principles.

From design to system architecture to basic vocabulary and communication patterns, our systems have grown organically since 2010 to support a powerful, diverse, and cooperative network of people capable of taking on environmental problems that affect communities around the world. The platform we have built together speaks to this shared history in many ways, big and small. It reflects input from people facing serious health issues, on-the-ground organizers, policy specialists, hardware hackers, educators, and civil servants.

This broad community, and the Public Lab team have facilitated a space where we can discuss, break down, construct, prototype, and critique real-world projects. Together we have shaped a platform that incorporates familiar pieces, but ultimately looks and feels quite different from anywhere else on the internet. Our platform continues to grow and be refined, but it also reflects a commitment to listening to one another, to mutual respect and support, to an awareness of the barriers and challenges presented by gaps in expertise and knowledge, and a sensitivity to the inequalities and power imbalances perpetuated by many mainstream modes of knowledge production and technological and scientific development.

Our mutual aims of democratizing inexpensive and accessible do-it-yourself techniques has allowed us to create a collaborative network of practitioners who actively re-imagine the human relationship with the environment. Our goals are supported and facilitated by a system which questions and even challenges how collaborative work can happen.

We could refine or adjust this! Here's a further brainstorm, and we'd love to hear more:

  • an easy to use platform for ____ (collaboration, organizing, regional organizing, collaborative project development, building a collective knowledge base?)
  • an equitable and respectful space for collaboration
  • a knowledge base that builds long-term ...
    • long-term easy-to-access and navigate repo of resources
    • quick and easy access to organizational pages (open hour, barnraising)
    • nuanced search (water quality, education)
    • serendipitous browsing (related, recommended) with human input
    • help to interconnect topics & organize knowledge
  • think on: integrating different entry points/perspectives?
  • well-integrated with other platforms (social, APIs, things like github or instructables or etc etc)
  • good integration with online and real-world events
  • for collaborative public research
  • clear and easier connections with store (and other PL online ecosystem)
    • and potentially /any/ other site

How to get more involved

(This may need more building out)


That's what we've got so far! We'd love to hear more, as we hope this document evolves into something that we can all look to as we build out projects and community here. Thank you, leave comments below!


11 Comments

I tweaked the "Ideas" section a bit, linking to our style guide and priority issues.

Reply to this comment...


Hi Jeff, great post.

  • Allow rewrites of site functions (like in React, which was a popular idea this year)... only? ...if they come with good (system?) tests

Wow! Excited to see this 😃.

  • Identify and rally contributors towards "big projects" we're trying to complete and recruit help on (rather than starting new projects?) to start to complete them and reduce our "technical debt" (is this a good frame? https://en.wikipedia.org/wiki/Technical_debt)

👍 +1 🙌

  • Encourage ppl to choose a segment of the code to specialize in (add your name to a group?) to build longer-term institutional memory and capacity to maintain the codebase (not sure about this one? Would love input!)

Agree on this. I think it's essential to specialize in any one of the repo as only then one can experience the different roles and can constantly keep on taking bigger challenges.

Newcomer --> Contributor --> Reviewer --> Maintainer --> Maintainer + Time to explore new repo and specialize in that 😃

Also, one can contribute to/review/maintain multiple repos at a time . It depends on person to person, how much time one has, the motivation behind contribution, etc.

yes, how to get involved section can be expanded. We can actually summarize it in steps like: - If you are new to Public Lab then try first-timers-only issue from https://code.publiclab.org - We only allow a newcomer to solve one issue but if you're still confused about GitHub flow and how things are working, then we can make an exception. If you got things clear, then proceed to the next step. - Undertake fto-candidate issue or help-wanted issue, they maybe a bit complex but you can definitely expect help from us. - You can undertake more issues at this stage of your Open Source journey with Public Lab. Also, you can consider creating an FTO issue for a newcomer and help someone start their OSS journey 🎉. - Moving ahead, you can take on challenging tasks, review PRs of other contributors and much more. You can also volunteer to be part of the Reviewers' team by commenting on an issue like this - https://github.com/publiclab/mapknitter/issues/634. - Keep on contributing, be an impact and get yourself maintainer authorization (needs more clarity!)

Thanks!!!! And, really love the note's image. You remember, there's an issue - https://github.com/publiclab/plots2/issues/4880 open for that 😃.

Is this a question? Click here to post it to the Questions page.

Yes! Love this Newcomer --> Contributor --> Reviewer --> Maintainer --> Maintainer + Time to explore new repo and specialize in that 😃

This connects with and builds on what @sashadev-sky wrote in https://publiclab.org/notes/sashadev-sky/05-16-2019/public-lab-s-contribution-framework-deep-dive-2019

Perhaps we could link from the first 3 steps to a longer "journey" we encourage people to take, that has these extra steps!

Re: diagram, yeah!!!! I was thinking of that when i made it, will add a link. It was a tough diagram to make, actually - and bigger and more complex than I'd expected!


Reply to this comment...


https://docs.google.com/document/d/1o0fY8dWVxVUqA_ppXl-LZ7vzVb5LqNUTzlrxy3PsS_Q/edit?usp=sharing I wrote a proposal a month ago for this. May be we can dive some points on roadmap from there.

Is this a question? Click here to post it to the Questions page.

That would be super, Sidharth, thanks a lot. Let's highlight some specifics that we could consider merging in?

Is this a question? Click here to post it to the Questions page.


Reply to this comment...


Thanks for sharing Jeff, it is a great post.

Reply to this comment...


  • This is so cool. Clears up some misconceptions. I thought Blurred Leaflet was part of Leaflet Environment layers! Now I know they are separate.
  • One suggestion is to update this chart or create a separate chart that identifies the software application. While I know this is for software developers, it would also be useful to have a ‘user’ ecosystem map. Links could also be embedded in the chart so you would have a single graphic that shows all of Public Lab software offerings. Something like: https://github.com/MargaretAN9/GSOC-2019/blob/master/sotware%20code%20ecosystem%20with%20apps.pptx

  • It may also be possible to show how the different GSOC/Outreachy programs contribute to the roadmap. I put together a comparison chart to show the different efforts but a relationship graphic may have been a better approach. Copy and paste the link below to see GSOC comparison excel chart:

https://github.com/MargaretAN9/GSOC-2019/blob/master/Comparison%20matrix%20Public%20Lab%20GSoC%20Outreachy%202019%20v1%20(1).xlsx

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


@cess 😃

Reply to this comment...


I updated this diagram!

Screen_Shot_2020-01-03_at_12.45.10_PM.png

Is this a question? Click here to post it to the Questions page.

Should we update the main image of this post to be this diagram?

Is this a question? Click here to post it to the Questions page.


Reply to this comment...


Update: software overview: we've just (as of Nov 2020) published a new Software Overview page with a detailed description of all our software projects, who uses them, goals and how they interconnect. Take a look!

Reply to this comment...


Login to comment.