Beyond the Technical Roadmap: Why, What, How, Who?

Beyond the Technical Roadmap: Why, What, How, Who?


Brian E. Granger

September 22, 2018


  1. Beyond the Technical Roadmap: Why, What, How, Who? Brian Granger

    Cal Poly, Project Jupyter NumFOCUS Summit, NYC September 2018 Cal Poly @ellisonbg
  2. Outline • Observations about Technical Roadmaps • Beyond the Technical

    Roadmap? • Why? What? How? Who? • This approach is founded on ideas from human centered design. • Activities • Not going to talk about: • Building consensus around roadmaps. • Roadmap process. • How to manage partnerships that emerge around the roadmap. • Managing the scope of a project.
  3. Roadmap: a map of where you want to go and

    how to get there
  4. Technical Roadmap: Observations • A technical roadmap tends to be

    written by developers and for developers. • Here is a test: Is the roadmap on GitHub? • This is not a bad thing, but best to be honest. • Developers are already doing regular work, and tracking that work using systems such as Jira, Github Issues, etc. • As a result, separate technical roadmaps often feel redundant with these other tracking systems. • They easily fall out of date with the actual work. • One approach is to have a technical roadmap focusing on the larger picture, rather than individual technical issues.
  5. Beyond the Technical Roadmap • Why would an open-source project

    want something that goes beyond a technical roadmap? • Users ≠ Developers • Many users of our open-source projects are not developers. • Many users of our open-source project are very different from us: • Skill level, language, education level, technical background, usage case, race, gender, country of origin, age, etc. • Many never visit our GitHub repos. Some don’t know that GitHub exists. • They would still like to know where a project is headed and when it might happen. • I am not talking down to users here in any way. We are here to serve them. • From a community growth perspective, it is still helpful to view all users as potential developers.
  6. Beyond the Technical Roadmap • Funders ≠ Developers: • What

    will happen if we give you money? • What is your record of delivering high impact work? • Who could do this work and on what time scale? • How will this work impact other projects and initiatives that we fund? • What will the impact of this work be on something that we care about? • Organizational Decision Makers ≠ Developers: • Users of your project in our organization need X, is that on your roadmap? • When is X likely to be developed? Released? • Who is working on it that we can talk to? • Who else is collaborating with you on this? • What is the business risk of waiting for you? Of building something ourselves?
  7. Framing Questions • One useful way for organizing a roadmap

    is as a set of questions: • Why? • What? • How? • Who?
  8. Why and What? • What are you proposing to do,

    and why? • Describe the proposed work from a user’s perspective, in non- technical terms. • Which users, both individual or organizational, will the proposed work impact and how? • How will the proposed work address those users’ pain points and usage cases, and what will they be able to do when the work is completed?
  9. What and Why? • Writing the “What and Why” is

    really challenging, especially with a large number of contributors. • This is the part of a roadmap that funders and organizational decision makers are going to look at. • A well written “What and Why” is like a catalyst. • Will require time and effort to distill something down to a short, non-technical description. • Short and non-technical!
  10. Example from Jupyter • The “What and What” of real-time

    collaboration: • “We propose adding Real-Time Collaboration to JupyterLab and JupyterHub to enable multiple users to share and simultaneously edit notebooks, text files and other documents. This will be built in a manner that does not require any outside services, to enable its usage in organizations that have private and sensitive data. This work will benefit all Jupyter users who are working in organizations and teams by enabling them to collaborate quickly and easily using a simple, familiar model, and without the usability challenges of version control systems or the tedium of manual conflict resolution. An additional side effect of the work will be a unified undo/redo system that works across all areas of JupyterLab.”
  11. How? • Provide a brief overview of the technical details

    of the proposed work. • Provide a table of descriptive milestones an estimate of the Full-Time Equivalent (FTEs) staff required to complete the milestones. • I realize that that time estimates are difficult to make. • At the same time everyone reading your roadmap will want to know “when is this going to happen?” • Self fulfilling: no organization will give you money without some manner of timelines. • Try: • Take your min estimate, your max estimate and add them together. • Provide a range (1-2 months). • Hedge • Tell audience what the assumptions are: “in these estimates, we assume the work is fully staffed.”
  12. How? • Like the “What and Why,” the “How” should

    be short (1 paragraph). • The “How” needs to be specific enough for people to act on, but vague enough to allow you to deal with uncertainty and the realities of open-source communities.
  13. Example from Jupyter • The “How” of real-time collaboration: •

    “We propose to build the TypeScript/npm package `@phosphor/ datastore` which implements a strongly-typed, flattened, and normalized relational datastore capable of synchronizing and merging the changes of multiple users using conflict-free replicated data type (CRDT) algorithms. This library will be integrated into JupyterLab as the default in-memory data model for all documents. It will be backed by a server component in Jupyter Notebook Server and JupyterHub which synchronizes changes among users and maintains the global history of each document. Our implementation will scale to many users, large documents, and be deployable in secure contexts (no outside services required).”
  14. Who? • Who are the authors of the roadmap and

    have signed off on it? • Who will be responsible for managing the proposed work? • What organizations are partners on the proposed work? • Who else is funding the effort?
  15. Who? • As contributors, we take these “who” questions for

    granted. • Users often have no idea who does what in an open-source project! • Being explicit helps with transparency and risk assessment. • It is fine to say, “we don’t know who!” • For any complex project, answering the who question will require private conversations: • Will you fund this? • Are you available to work on this? • Who would be hired to work on it? • For open-source projects that prioritize transparency and open consensus, this requires thoughtful processes around authoring roadmaps.
  16. Activities

  17. Groups! • Break up into groups of 3 (4 at

    most) • Group with people who are not part of the same open-source project. • This will help you to think and communicate in non- technical terms.
  18. Activity: Major Proposed Work • What would your project want

    to work on if it had funding for 3-5 years? • Thinking about that time frame, list major work areas your project would like to tackle. • Pick an approximate time interval for what you consider “major” work: • 6 - 12 months is a good starting point • First work individually, then share your ideas with other group members. • Aim for a list of 3-5 areas of major proposed work. • Can be code, design, community, governance, maintenance, etc. • It may be helpful to break ambitious work into smaller parts. • It may be helpful to combine smaller work into larger stories. • Aim for units of proposed that are focused, concrete and specific.
  19. Activity: User Groups/Personas • Pick some of the major work

    areas, and list the different user groups/personas that would be impacted by the work. • Alan Cooper, “A persona is a user archetype you can use to help guide decisions about product features, navigation, interactions, and even visual design.” • First work as individuals, then share with group members. • Jupyter examples: • Data scientists working in companies. • Scientists doing academic research. • High-schoolers learning to code. • DevOps teams deploying Jupyter to a large scientific collaboration project.
  20. Activity: Pain Points • Now focus on one major work

    area + user groups. • What are there current pain points related to that major work area. • How would those pain points be resolved if the work is completed. • What will they be able to do if the work is completed? • How will they be happier and more productive?
  21. Homework • You have brainstormed about the “What and Why”

    parts of a roadmap. • Try to combine all that into at most 2 sentences that capture the idea • Example from Jupyter: • “We propose adding Real-Time Collaboration to JupyterLab and JupyterHub to enable Jupyter users working together to share and simultaneously edit notebooks, text files and other documents.”
  22. Writing • George D. Gopen, “The Sense of Structure: Writing

    from the Reader’s Perspective”(2004).
  23. Reading • Alan Cooper, “The Inmates are Running the Asylum”