Community Visibility/Tooling

For our upcoming ODK 1 dev calls, we will need some sort of note-taking platform. We've usually relied on Google Docs for this, but I don't think it's viable for this community long-term. Just the fact that individuals would own the documents is a non-starter.

I'm leaning towards etherpad and I'm curious what folks who've used it think. Etherpad feels like a great Google Docs replacement, but maybe I'm thinking too short term and maybe a wiki is better?

I tend to hate wikis because they don't have great live editing (e.g., Discourse's wiki) and then we'll have to have the community create yet another account (e.g., Confluence) and then we'll have to explain what goes on the forum and what goes on the wiki and what goes in docs and what goes on the website, etc.

Anyone know of a silver bullet?

1 Like

Etherpad is great for production of docs/notes, but very poor at both searchabilty & findability. There is not much of a search feature across existing pads (security by obscurity).

Generally I recommend folks very quickly move etherpad "docs" over to a more permanent home such as a Discourse wiki-fied topic, a doc repo, or a wiki platform such as the one built into GitHub, etc.

1 Like

And your thoughts on Discourse vs Github vs Confluence as a the wiki for the community?

  1. Confluence definitely seems like overkill. It's quite a resource hog and may be great for large-scale collaborative organizations, but that doesn't seem like where ODK is these days.
  2. Discourse is very feature limited as a wiki but relatively easy to use for non-developers, who can be reasonably expected to already have an account.
  3. GitHub has better "wiki" features, but the wikis are generally split across repos (bad) instead of organization-wide. (Or you've got to make a special repo for project-wide stuff like wikis.) It also requires non-devs to get a GitHub account and learn the basics.
  4. Alternatively, Etherpad supposedly has some "wiki" plugins that on the surface might help with findability of docs. I have not used them, but could be promising! https://static.etherpad.org/plugins.html

Reviving an old thread here, but I think that a Jira/Confluence combination might be really helpful for ODK. Neither of them is among my favourite tools (to say the least), but:

  1. They work well together
  2. They're free for NGOs in their cloud form (which means no self-hosting, which means that @downey's totally justified complaint that Confluence is a resource hog would not be relevant)
  3. If the initial set-up is done well, they can actually work pretty well for a project/organisation of ODK's size, without being too overwhelming

Some thoughts/motivations:

Jira

On the first TSC call yesterday I talked about the value of a board/ticket structure for defining and refining tasks (i.e. the work that needs to be done before any code is written), and I think that thinking in terms of epics, stories, etc. could be very helpful to get an overview of the roadmap. And of course once that's done, the board/ticket structure becomes very useful for tracking implementation progress.

It also provides an easy public view onto both the current state of play and future plans and priorities.

The main downside is probably that in order to be useful, a Jira board requires some upkeep.

Confluence

In the collaborative writing vs wiki debate, my favourite answer is actually "both". I prefer to use a tool like Google Docs for brainstorming and discussion, and then copy/paste over to a wiki for a more "permanent" home, with the possibility of comments and discussion below the fold. (Ah, looking back, I realised that I've just repeated what Downey said here...)

In the end though, I don't think it makes a huge amount of difference which tools you pick, as long as you commit to being serious about using them.

2 Likes

I wasn't in this meeting to get the full context, but has anyone thought yet about whether or not GitHub's project management tools and boards would be sufficient here? I know you can get things like milestones, epics, and stories as well as Kanban/issue boards in GitLab, but haven't tried the equivalent tools on the GitHub platform to understand the differences between the two.

AFAIK you can't have epics on GitHub boards, which would be a shame, especially since one of the main motivations for using a board is to facilitate roadmapping. Zenhub adds epics to Github, so that might be an option.

Thanks for starting this conversation way back when @Jake_Watson and for reviving it @adam.butler

At the risk of restating what has already been said, here are the most pressing needs that I currently see:

Most of these needs could probably be addressed by process changes but even better if there are tools that will provide more support. I've seen Jira+Confluence used to good effect in other open source projects and haven't seen anything else I was blown away by so I'd be ready to try.

:100: Thank you, @adam.butler, that is a really important point.

1 Like

@TAB we'll no doubt be discussing these issues in our next call but it might be helpful to start with some impressions and ideas discussed here. I think it will be really important for us to have a process for making our work visible and answering the question of where it will all go is really important.

Just noticed your comment. Yes, ZenHub is a free-of-charge-for-open-source SaaS (proprietary) overlay to GitHub issues that provides a lot of Kanban tools, Epics, etc. I haven't done anything beyond messing around with it, but I believe @wonderchook has used it. AFAIK they use all of the existing GH data structures for additional organization, so it isn't necessarily required to use ZenHub to work on bugs, etc.

1 Like

Might this be a good landing page in the "Developing With ODK" section of http://docs.opendatakit.org/?

We did use it and it worked well for us. Then we switched to using all the tooling in Github when the projects functionality was released there.

2 Likes

Hi @adam.butler,
just a quick question/clarification. I see that Jira/Confluence are free for "non-profit charitable organisations". AFAIK this is different from just NGO.
Only those bodies registered with the Charity Commission can call themselves charities.
Is this correct?

I think ODK is eligible for an open source license - https://www.atlassian.com/software/views/open-source-license-request

3 Likes

Yes, sorry, I was getting my affiliations all twisted :slight_smile: - ODK would fall under the OS category. FWIW, in my experience Atlassian are fairly flexible in their definition of “non-profit charitable organisations”, if you ask them nicely.

During the last @TAB call, there was agreement to start with GitHub Projects since it's lighter weight than other options discussed and issues are already tracked within GitHub.

I started https://github.com/opendatakit/roadmap/projects/1 as a quick demo of how this could work. I like where it's going but notes seem too lightweight, especially since they can't be tagged. I propose we create a organization-level board so that we can include issues from all of the various repositories. All @TAB members should be able to modify it.

For higher-level feature ideas that need to be specified, we could create issues in the roadmap project linking out to forum posts and other resources. We would choose a combination of columns and tags to track progress (e.g. "needs champion", "needs wireframes", etc)

Here are a few projects that use GitHub projects for roadmapping:

@TSC, please share your feedback. I believe @yanokwa would need to create the organization-level board and provide access.

2 Likes

Thanks for taking the lead on this, @LN!

I really like the idea of an organizational level board and I've created a tentative one at https://github.com/orgs/opendatakit/projects/1.

I've split up the boards like so:

  • Long term: Needs a shepherd and a specification.
  • Short term: Needs developers and a deadline.
  • Doing: Actively being developed.
  • Done: Shipped!

Cards move from left to right and we can just drop whatever issues we want into the various columns. For epics (e.g., performance improvements), we can use checklists in issues filed against the roadmap repo and it becomes pretty easy to see.

Does this setup seem reasonable? I'm new to GitHub projects and I'm particularly interested in hearing from folks who've used it before.

I think we may need a section for whether an idea may have been assigned to someone or a team though it may not be actively under development. Or does doing include stuff that are still in discussion or specification phase?

@yanokwa kwa Is the org project or private? I get a 404 on the link you shared.

According to https://help.github.com/articles/about-project-boards/, only organization members can view and create organization-wide project boards. MADNESS.

I've invited all TSC members to the ODK organization as a first step. I've also found a workaround that will take that data and publish it. I'm hoping to have that live in a few hours.

The workaround was more complex than I thought and still didn't work. :cry:

Given that organizational boards won't work, I think we should revert to @LN's initial idea of a project in a roadmap repo. All @TAB members have access to the project and I've confirmed that those are public (see https://github.com/opendatakit/roadmap/projects/1) and we can use tags!

Per @Ukang_a_Dickson's feedback, I've also adjusted the roadmap into four columns: Needs proposal, needs developers, doing, and done. I'm hoping this this contribution-oriented naming is more welcoming.

I've put the high-level features we are working on in the Done column. For future reference, just copying and pasting the URL from an ODK project will embed the repo-specific card.

To get us started, I've also put the features that TSC members showed interest in during our call as Needs proposal. I think anyone can file an issue, but it's the TSC that will decide what goes into each column.

The proposal discussion can take place where ever (e.g., forum post for more user-facing features, a GH issue for more technical discussions). Once we something actionable, the proposal can be filed as a single issue on the relevant repo or if it spans multiple tools, then an issue on the roadmap repo will be the best option.

Then we can move the proposal to Needs developers. At this stage, it's a matter of resourcing and adding a timeline (I'm hoping tags like Q2-2018) will be sufficient here.

How is this proposed process sounding to folks?

1 Like