Community Visibility/Tooling

Just wanted to clarify my remarks today during the conference about making the backlog, roadmap, etc. easier to follow and view.

I guess I was trying to get at a suggestion for a more user-friendly tool to view and follow than the stock GitHub issues tool ~

The new forum is a really good first step, but I wonder if something like the Atlassian suite might make it even easier? (And there are others out there; I know people have perhaps a love/hate relationship with Atlassian's tools).

The cloud-hosted suite (Jira, Confluence, etc.) is free to non-profits. Not saying it is the best tool, but we find it way easier to view, manage — and make transparent to the community — than straight GitHub …

For example, here are views we use to share information with the OpenLMIS Community (and manage ourselves):

We’ve got a pretty small team but a lot of interested community members, and this has really helped us keep things transparent and avoid the need to put together status emails & reports.

FWIW

3 Likes

And, of course, I neglected to point out that everything is wrapped and linked to from http://openlmis.org/
-- dev links to 'readthedocs', which are automagically built and published with the code, etc.

Thanks for sharing your process and tools! :tada:

If anyone is interested in starting to explore some of those tools and how they would fit in with the existing communication channels and web presence, that would be awesome. I think looking at how some other open source projects share this kind of information would also be valuable.

Just a couple other tools I've used on top of github for help with this sort of tracking and sorting, all provide a Kanban board type of view.

  • Waffle: Loads github issues directly in and as you update them it will update the ticket.
  • Github projects: I haven't figured out a good way to make this public at the moment. You have to be a member of the org to see.
  • Zenhub
1 Like

Good tools assembling here! Within DIAL "internally", we are using GitLab over GitHub and others (even for non coding projects) because of stronger kanban board support built in, and roll up of issues across repos/projects into a single organization/group. It also has a "service desk" feature per project that allows people to email in bug reports without having to create an account or interact with the GitLab UI. GitLab is also open source so we could easily start hosting it internally if needed at some point, or ostensibly get better access to our data.

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.