Discussion on open roadmaps and tooling for it

Aha! Link: https://ushahiditeam.aha.io/features/PROD-29

I think it'd be good to get @mackers input on this and...maybe if @jrtricafort @caharding @jshorland are interested in doing some OSS contribution 🙏 🙈

In the spirit of "working in the open" , this is my personal take on roadmaps. Of course you are all very welcome to disagree and tell me :D :)

Roadmap design

The default state of our roadmap will be open to everyone, not closed.
Closed/Private items will be the exception, not the rule.
We make strategic decisions for our roadmap that help the organizations and people we serve. This means deployers and end users. Often this will mean saying no to prioritizing a feature that we believe is important but not the most important thing to work on right now. We collaborate, we seek feedback, we learn from others and share our learnings. We do not, however, design a product by committee.
There is a single responsible individual for ensuring the roadmap is good, up to date, and makes strategic sense. This does not mean "this person makes the roadmap", it means "this person is ACCOUNTABLE for having a good roadmap that can be executed upon.
[tooling] New roadmap entries will come in the form of pull requests, as this is a well known way to contribute to any GitHub repository and allows people to give their thoughtful comments on each suggestion, accept it, edit it, or reject is (and there is a clear log of each of this actions, with dates!) . -> OK so this might be the developer in me talking but I think this is likely super doable for non-devs since GitHub as a decent UI now? I'd love it if we could centralize the roadmap in GitHub and this is the best idea I have so far but probably someone else will have a better one.

Our roadmap should have the following characteristics

easy to understand.
updated often; it should be up to date.
detailed content up to 1 month.
fuzzier as it gets farther away from today.
ownership should be obvious as you look at it.
links to detailed conversations that explain the full scope of an item should be easy to find, available, and useful.
it should contain the rationale for the decisions contained within it.
it should be open to modification as priorities change.
it should be editable in GitHub with simple markdown in a file, which is where everyone is already (see my comment about pull requests in the first section for this)

Totally fake roadmap Q3 and Q4 2019

Here's an example of what I envision (note that while all the items are real, the priorities might not be because I made them up in the spot) in terms of amount of content and format. I'd like to integrate some icons here for sections but mostly keeping it simple. Also note that this would be in a document in GitHub, probably as its own repository that folks could link to, send pull requests to, and modify through those pull requests.

Deliver [confidential GrantName] technical documentation [August 2019, first week]

Owner: Romina Why: we are working with a group of organizations as a consortium to deliver the [GrantName] project, and this technical documentation is key for understanding how to setup platform and how the projects fit together to deliver value.

Follow all [GrantName] project work [in this link](this project is real but not linked here)

Launch the DevHub. [August 2019, end of month]

Owner: Anna Why: we made a commitment to create a developer hub. This will be honored by the team. We believe the developer hub will provide value to current and future contributors as a place where all the knowledge they need is linked together, easy to follow and easy to edit.

Follow all DevHub tickets here https://github.com/ushahidi/platform/labels/Theme%3A%20DevHub

Finish the installation helper [September 2019, first week]

Owner: DavidL Why: we believe the installation helper will be a valuable tool for new contributors and folks setting up platform for the first time, as it provides hints and support links that will point new developers in the right direction. We think this will improve the ability of new contributors to submit their first PR within days, not weeks, of learning about Platform.

Follow all Installation Helper tickets here https://github.com/ushahidi/platform/issues?q=is%3Aissue+is%3Aopen+label%3AInstallation

dates and details on issues gets even fuzzier here , as we move to another quarter

Create a UI test automation suite that everyone can contribute to [Q4 - 2019]

Owner: Walter Why: to improve the ability of the team to deliver working software in a shorter timeframe with confidence. This will allow QA specialists with some automation knowledge to contribute their own tests to the platform.

Follow test automation work in this experimental repository https://github.com/ushahidi/experimental-e2e-testing

Lower the number of requests needed to load data view and forms [Q4 - 2019]

Owner: dev team Why: because the site will be faster and more reliable for all users. It will also lower the complexity of obtaining each view in the frontend code which will lead to simpler, easier to follow code. Follow ideas for this ticket here https://github.com/ushahidi/platform/issues/2392

edit: Noticed that http://canny.io has been discussed for this too. It looks nice. My only concern so far is that it divides "feature requests " and makes them go outside of GitHub, but maybe that's solvable? Not sure. If we really like it I think we could integrate and "duplicate" the issue so it comes into GitHub with a Zap (from zapier) if we have a paid zapier . I would like this to be super integrated with our normal tools (to avoid another situation like ZenHub where it felt disconnected from OSS) but also usable for people who aren't devs.

@rowasc I love it! Very clear and this:

The default state of our roadmap will be open to everyone, not closed.

is awesome! I would be interested to hear a non-devs point of view of using github though.

The default state of our roadmap will be open to everyone, not closed.

LOUDER FOR THE PEOPLE IN THE BACK :D:D:D:D 🙌 ❤️ 💐 ☝️

We make strategic decisions for our roadmap that help the organizations and people we serve. This means deployers and end users.

End users = beneficiaries of the deployments x 1000 yes. We should understand these people as well as we understand deployers.

[tooling] New roadmap entries will come in the form of pull requests, as this is a well known way to contribute to any GitHub repository and allows people to give their thoughtful comments on each suggestion, accept it, edit it, or reject is (and there is a clear log of each of this actions, with dates!) .

I have to agree with Anna and disagree here. People that are 'non-developers' (otherwise known as, GitHub is not where they spend a majority of their day to day on) are actively scared of github. So this includes designers, creatives as well as most other work functions that basically, don't do coding. This requires a level of digital literacy and access which is daunting. We can for sure start with an open roadmap on github but we need to be willing and ready to do an educational, digital literacy piece on supporting people to contribute this way OR facilitate another way of contributing to the roadmap via a google form, contact form, ushahidi deployment etc.

I'm totally up for and interested in discovering how critical the above is to our short term success (i suspect it is not critical) but for long term inclusion it is critical and even in GitHub's best interests to support and understand.

easy to understand.

We'd need to understand what is widely meant by this? Do we need translation? etc.

links to detailed conversations that explain the full scope of an item should be easy to find, available, and useful.

This requires us as the lead team to collect and document conversations or record all conversations relevant to a feature to then be able to make this public.

simple markdown

Markdown isn't simple...I still struggle with it...

pull requests.

We need to show and train on what a successful pull request/push request/adding content review process is through like...a video or something. We need to assume some folks have 0 understanding of this when they come to contribute.

Why: to improve the ability of the team to deliver working software in a shorter timeframe with confidence. This will allow QA specialists with some automation knowledge to contribute their own tests to the platform.

Some of these things will need a very basic explanation of what the thing is...and how they can contribute. I would suggest a section after each roadmap item that suggests people we think might be interested in contributing so e.g.:

Create a UI test automation suite that everyone can contribute to [Q4 - 2019]: Quality Assurance testers, anyone interesting in testing software, people that already use X platform, people learning X... ^^ this is probably not a great list but really we could be suggesting the pathway people can self-learn on to be able to contribute to a given roadmap item.

I'll take a deeper look at canny.io but really, at a glance it still looks like a technical product and I'm skeptical about how inclusive it is... 🤔

Thanks Eriol, this is useful.

Markdown isn't simple...I still struggle with it...

Alright, I hear you. What is a simple option that everyone is familiar with already?

Some of these things will need a very basic explanation of what the thing is...and how they can contribute. I would suggest a section after each roadmap item that suggests people we think might be interested in contributing so e.g.:

Yes to adding "how you can help" sections on all.

I'll take a deeper look at canny.io but really, at a glance it still looks like a technical product and I'm skeptical about how inclusive it is... 🤔

I don't have a preference for canny, I just read in a doc from support that you or others were looking into it. I am not sure what you mean with "a technical product" to be honest...

more thoughts on tooling:

For me an important consideration on all this is that whatever we do for submitting roadmap suggestions, and for presenting our roadmap plan to readers, it needs to be something that we can have versioned so we know how it's changed over time (even if that's just a simple enforced Change Log in a file and not in a git repo, of course!) and that we can link to it from any file/website so it's easy to share it. I really don't want people to have to login to an app/website just to see the roadmap, but I assume they will need to login somewhere to submit to it..

There are different users types for this, some people can be all these at different times, other folks will probably just want to be able to read it and understand it. I have a feeling that google forms are not ideal because you can't continue a conversation through them. Email, Forums, Github, maybe even Canny are all things that you can have a conversation on. The challenge is that you have to have the same conversation in all of them. Users chatting through a feature in GitHub need to see the same as users sending emails (of course, GitHub supports emails, and forums do too). We will need to find one way to submit and chat through a roadmap item that we can all live with and stick with it.

Some of the requirements for this, as I understand them:

review past issues
submit suggestions, have a way to be notified when there are new comments
discuss the submissions from everyone in the open
make a decision on next items that get added to the roadmap
display our plan (+how to help, dates, effort, lead, etc etc) for each month/quarter
link back to the original submissions for reference and notify that it was added to the plan
track and understand the progress made vs roadmap plans made, and adjust based on it
be able to decide what to collaborate on based on the roadmap details and skills needed
Link back to actual tickets where we are working. Important feature: If the submissions are sent to another tool that is not GitHub, then github issues and comments on them need to be sent to that other tool too.

This would support our goals of openness, collaboration and co-creation.

All this is possible in GitHub which is why I think it's the most approachable solution right now, but if that's not feasible because nobody knows how to use GitHub, then the alternative IMO is a Github+Whatever 2-way integration, because people will continue submitting to GitHub unless we block the repo from accepting issue submissions.

User action types maybe?

Some types of user actions/goals I think we'll have for this, since it may help guide our conversation (or it might uncover that we all think about it differently):

Stakeholders and other "readers" and evaluators of the roadmap

People who want to understand our progress towards a roadmap to hold us accountable to it
A deployer reading the roadmap to be informed of what's coming next (reader)
Large orgs (ie enterprise) that want to know the future of our platform (reader)

Submitters:

A person interested in a feature who wants to have their suggestion accepted into the roadmap (submitter ? eh I may need a different word for this)
Someone showing support for a feature (ie "Voters")

Triage(r?):

Someone who triages issues as they come in and identifies priorities to suggest putting them in the roadmap in the short term

Approvers:

People who approve roadmap items (typically a product manager, or whatever is given that mandate within the organization) -> of course, this does not mean they make a decision alone based on just what they want, it just means they are accountable for making it.
This is typically a Ushahidi staff, supported by the inputs of the organization, contributors, etc

Editor:

Someone who creates the "presentation"/file with that roadmap in a readable format that is easy to understand. They don't necessarily do this alone, but they are accountable for it. This can be anyone.

wild idea. Also totally the opposite of what I was saying probably but maybe a good middle ground that serves more types of users than just devs and give us more tooling.

Maybe we should consider basecamp as "the hub" for both our community and staff to collaborate? it seems to be built for humans, which is nice?

https://basecamp.com/pricing it has unlimited users for $99 a month which is awesome because we can have our community there too! , as long as we find a way to ensure the roadmap is always publicly visible and it's easy to signup and collaborate on it, so that we can achieve open roadmaps. I am assuming there is some kind of integration with GitHub in which case it could work great, while giving us decent tooling (which I selfishly really want. But I'm more than willing to sacrifice tools in favor of openness!!!)

https://basecamp.com/yes -> what the current version of basecamp can do, apparently

They offer a trial version for a month, so if there's any interest we can check it out as a team and try out how accesible it really is (or isn't) and how much it would help or detract from the goal of openness and co creation with a community?

Is this a dumb idea? It might be! it just occurred to me while looking at how pretty their docs are (seriously look up the rails docs and the basecamp docs and everything else if you haven't)

I'm not very committed to the idea of using it, just floating it here to find what your thoughts are:)

PS: note that whatever we end up doing, GitHub integration will be important (at least I think so), especially tickets/conversations and a way to participate in them from [whatever-tool] easily .

Cloned this issue. The DevHub/DIAL issue is here https://github.com/ushahidi/platform/issues/3645

Mural also has a github integration for the cards created if we like that tool.

Basecamp is totally worth testing. I think we should just be careful to think that any 1 tool can solve tech-shy people or the digital literacy issues. I think you'll still have people just wanting to talk at people/us or writing huge emails and they will expect us to transcribe. This is especially for those not comfortable with written english.

Does basecamp have multi language functionality? I'm sure it does :)

i think we also need to solve the thing that we do internally where different functions have conversations in different places. e.g.

I talk more in slack

Devs talk equally in slack/github(? assumption)

Implementation talk in emails/in-person/slack (? assumption)

Mural also has a github integration for the cards created if we like that tool. I think Mural is great for brainstorming as a group, live, and my favorite thing about it is that everyone "gets it" now. For something more long term than a brainstorm, I feel it's super slow to use/not very nice to write in? I really dislike it for reading after the fact too, because of the amount of scrolling, and a super slow scroll at that. It doesn't feel comfortable to use, but again this is a very personal opinion based on how I use tools, not a "this is bad UX" type of opinion.

I think we should just be careful to think that any 1 tool can solve tech-shy people or the digital literacy issues. I don't expect any given tool to solve it, I do expect tools can improve the experience or make it worse, if that makes sense.

Languages I just checked and Basecamp3 does not support multiple languages, which is potentially a problem if we plan to handle multiple languages in issues. You can customize most of Basecamp per project to use whatever words we want (ie I renamed "Campfire" to "Sala de reuniones" ) but there isn't a way to change the UI dynamically to every language which is what I assume we are discussing. That's a concern for sure that I failed to acknowledge.

i think we also need to solve the thing that we do internally where different functions have conversations in different places. e.g. Yea. It's something to be addressed, and I guess to solve for, to some extent. No tool will solve this on its own. Some tools will help reduce this, and others will cause more of this.

Devs talk equally in slack/github(? assumption) TLDR: It depends. I kind of assume tickets are in github, code reviews are in github, and the rest is ...somewhere. When I'm not sure where something is (except for tickets and code), I start with slack search, then google drive, then github search if it makes sense.

Implementation talk in emails/in-person/slack (? assumption) I make the same assumption but would need to ask around. This might be a nice poll for the AHC time slot actually "where do you communicate most of the time" and "what types of info do you look for in each place" for everyone to answer.

On Mon, Aug 26, 2019 at 2:21 PM Eriol Fox notifications@github.com wrote:

Mural also has a github integration for the cards created if we like that tool.

Basecamp is totally worth testing. I think we should just be careful to think that any 1 tool can solve tech-shy people or the digital literacy issues. I think you'll still have people just wanting to talk at people/us or writing huge emails and they will expect us to transcribe. This is especially for those not comfortable with written english.

Does basecamp have multi language functionality? I'm sure it does :)

i think we also need to solve the thing that we do internally where different functions have conversations in different places. e.g.

I talk more in slack

Devs talk equally in slack/github(? assumption)

Implementation talk in emails/in-person/slack (? assumption)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/ushahidi/platform/issues/3584?email_source=notifications&email_token=AASSKYLRHSJYKPBB3BCW4TLQGQGKLA5CNFSM4H4O7DF2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5FBHQY#issuecomment-524948419, or mute the thread https://github.com/notifications/unsubscribe-auth/AASSKYJ6EO4Z3R634C74IJ3QGQGKLANCNFSM4H4O7DFQ .

ushahidi / platform

[Future] Platform roadmap documentation #3584