Here we compile advice we have provided over time to our strategic projects (starting with Opencast). The aim is to create a generic template for typical community development support that we can use in engaging with future project communities. A workflow for engaging with strategic projects is being developed based on RG's earlier communication plan; see also EngagingWithStrategicProjects page
Discussion on list vs. jira and confluence
> I personally find the comments in confluence get lost fairly easily. We should try to minimize where we make comments. If we were disciplined enough to refer everything back to the requirements in Jira, I would say we can comment anyway. I think that having all discussions happen on list certainly supports transparency and simplifies where to find things. We can always add specific threads as a comments in confluence or jira. By using only one channel, we may expose ourselves to information overload. There may be so many discussions happening that it becomes distracting. Neither approach is perfect.
> +1 for comments on list only I'd be very happy to help people manage email overload. There are techniques that help (I receive upwards of 2000 emails on an average day, not including spam, obviously I don't read them all). The first, most important tip of all, is to set up an email filter for your own name in the body of a message. Flag such mails so that they catch your attention (i.e. star them in Google Mail or colour them in Thunderbird etc.) By doing this and ensuring the community knows this is common practice people can say things like "I think Joe had some ideas about that" and "I wonder what Jane thinks since this has overlaps with her work". Readers who are busy can then home in on threads that mention their name when they are particularly busy and use subjects to help speed read other content.
> +1 for *discussion* on list only, non-contentious comments as reminders or pointers can go straight into JIRA (you have JIRA to send comments to the mail list right?)
text vs html
> Here is my first stab at a weekly update (June 8-12). This email is quite dense, so if you prefer another format, additional or less info, please let me know.
> I like the format except that it is HTML. HTML breaks in many mail archive and search tools. Can I suggest using a text only format. The Markdown Wiki syntax  is really useful as it means mails can be HTMLified if necessary.
> I think that I can send as text and html through my Thunderbird client. Does the archive tool choose the more acceptable mime/type?
> That depends on the tool. The fact is that we have no control over what tools people use. Think of a PINE user for example. Netiquette still says no HTML (HTML + Text is just a waste of bandwidth). Perhaps, even more importantly, HTML breaks inline commenting. Not that in this mail there is no distinction between what you said and what I said. I use GMail as my mail client, so this is not some old hand refusing to move from PINE (although I do use PINE too)
weekly updates on decisions made vs updates on proposals made + lazy consensus
> I also wonder why this is being sent as a single monolithic document after the events have occured. In my opinion (and I know peoples opinions will vary here) these should be reported to the list as they happen and in separate emails so that people can comment on them if necessary. If someone prefers a weekly update then they can subscribe via the list digest instead.
> This is in reaction to comments that the email list is too informative, and that individuals would like a richer weekly synapsis than a list digest. It also is another opportunity to bring people onto the same page.
> OK, if there are no surprises in the weekly report for those following the list then that's fine. Thank you.
Of course, I may be showing my ignorance here. I know, for example, there has been some discussion of VP-Core on this list and therefore what is in this update may be a concise reporting of these issues. In which case I applaud the effort and hope that the community will not fall back on private working with a weekly update (things get forgotten and this breeds mistrust - I've seen it many, many times).
> Regarding your comment "will not fall back on private working with a weekly update", my intention is to better inform the community and bring them into the conversation rather being lost on list. The update should give everyone an opportunity to correct misstatements as well as add any omissions. The VP-Core update is in reaction to "private meetings" that happen offlist and should be a concise report. My hope was to bring ideas/suggestions that come out of these important meetings on list for comment. The status email should also call out decisions that have been made or questions that are still open, and hopefully facilitate decision making. For example, some threads gain momentum, but then they linger without a clear idea whether a decision has been made.
> I may be misunderstanding things, but this potential misinterpretation is what concerns me from an inclusion perspective. My concern is that decisions should not be made in meetings that are closed to some community members and then reported as a decision in a weekly update. The impression is that nobody has input to this decision. This is especially true for newcomers who don't understand the processes. Separate emails with [proposal] subjects are likely to encourage participation in the decision making process. A half way house would be to report decisions as proposals in the summary email (which is truly useful despite my concerns). Given that you operate lazy consensus this has no real effect on governance, but sends a very different message to those who read the summary mail. I appreciate this probably seems like "nit-picking", but the "devil is in the details" and I'm trying to look at things as a complete newcomer to the project in 12 months time when the "old hands" take all these things for granted.
tagging discussion topics using hash tags to allow aggregate searching
> I tried to tag stuff using brackets so that list subscribers can query this email or nabble. For example, I tagged open questions [Open Question] and decisions as [Decision], and glossary terms as [Glossary], and requirements as [Requirement]. I encourage everyone to read this and include comments and omissions to this thread. Thanks!
> Excellent idea. This is really useful I'd encourage people to use these tags as much as possible, although I'd encourage their format to be the same as HashTags, e.g. #OpenQuestion, #Decision, to allow aggregated searching in the future (not sure if anyone would do implement it, but if opencast has multiple projects in the future it would be a useful cross project collaboration tool)
> great idea right back at you.
> FYI this has recently been discussed on the ASF lists, so I'll be watching this experiment with interest so that I can report back about how effective it is. Thanks for that.
reply in separate mails + change subjects to keep archives clean
> Finally, can I ask that we adopt a policy of replying in separate mails and changing the subjects to keep the archives clean. Otherwise these could grow to monster threads.
> So the practice should be, continue discussions on existing threads, or spawn new threads if they don't exist? Responses to status threads should only include omissions or clarifications?
> Yes. I wonder if your reports could link to important threads in the archives - quite a bit more work, but useful for project memory. Probably something to do for issues that have created much discussion.
Acceptance Test language in Jira vs. Confluence requirements
> I think Confluence should provide supporting documentation for acceptance tests. Acceptance tests should outline what it means to be done, but confluence provides the detail. Links should be provided in Jira comments to confluence. Referenced Confluence pages must include their version number.
> +1 for confluence for details, and acceptance tests for high level outline.
> +1 although I am of the school that all testing should be automated and therefore self-documenting. In general though JIRA is a better place for any form of documentation. Having said that, the user lists (when you have users asking questions) are usually the first place documentation is found, so JIRA issues to "wrtie documentation for FooBar feature" will contain links to the archives and later a confluence page.
Requirements gathering workflow
> Project leads add story cards to the product backlog.
> Why project lead? why not anyone? I would imagine the project leads job is to ensure stories are adequately detailed. So you might have a workflow like this: a. story title is set an outline description is provided b. story is reviewed by project lead and either: b.1. given additional project details such as priority and component and marked as accepted b.2. commented as being incomplete with a request for additional information from the requester
> Led by a project lead, the team will determine who should be assigned to each task within an iteration.
> This is fine when you have paid staff to instruct to do certain tasks. However, it will not work when paid staff are not available. So lets plan for a situation where there are no longer paid staff in the project (always build for sustainability).
The problem I see with the workflow defined is that it provides no means for volunteers to take up a story. I'd therefore suggest that anyone can implement any accepted story at any time as long as they do the work. This means you need a parallel workflow to this one that provides a means for this to happen.
> Add final hours worked.
> I have no objection to tracking hours worked but wonder why you want to do this. I expect the data you collect will be innacurate. On an aside are you familiar with Mylyn  - very very useful tool (if using Eclipse). encouraging developers to use this and building your workflow around it will significantly help collect data like this and should help ou developers conform to the workflow.
Documentation licensing aligned with code licensing
I was wondering about licensing of documentation, including the opencast site itself as well as the confluence site. (Have I just missed the discussion around this?)
- Matterhorn is ECL (but there may be non-ECL bits of code in the wider OC community)
The OpenCast project site is CC-By-SA
The confluence site doesn't seem to have T&Cs.
Given that ECL was chose for Matterhorn (rather than GPL), would it also make sense to choose CC-By for documentation, and the website (rather than CC-By-SA)? Of course Matterhorn and the OCC at large aren't the same, but I was wondering whether there was a reason we may have chosen CC-By-SA for the site, and ECL for Matterhorn?
Given that the confluence site doesn't have a license, do we need to discuss how confluence site content will be licensed?
I'm asking this because we might start writing some community tutorials on encoding etc (for instance on confluence), and it would be good to discuss the license up front.
> Good question Bjoern. I could be mistaken, but I don't think this decision involved any deep consideration. Since the wiki supports multiple projects, should we give each space the ability to specify their own license? Or do we simplify it by "decreeing" that all Opencast projects are license X? To broaden the discussion, should we assume that any software project under the auspices of Opencast license their work as ECL compatible?
> +1 for decreeing, makes life much easier in the long run.
> From a documentation standpoint, I think it makes more sense to adopt the CC-By for documentation to remain consistent with ECL. I personally don't think that projects should be concerned about the commercialization of their documentation. And to simplify matters, we should have CC-By for all Opencast wiki spaces.
> [devils advocate hat] It is very hard to get people to write documentation. Those who know how to do something are the ones least likely to write it down. A common business model in open source is for people to sell documentation and support. This means that third parties need to write documentation. Now, is it acceptable to the project for someone to take the documentation that has been written by the community, add content and then sell it on? Do you want to force documentation back by using a SA licence?
[Devils advocate hat off] I don't think opencastproject.org should have multiple licenses since it is a community, cross project entity. I propose that this is CC-By as well.
> +1 CC-By for all wiki spaces > +1 CC-By for opencastproject.org
> +1. Encouraging people to compete in the support space creates more support for the products, which increases the developer pool.
Leading by example
In a recent discussion about effective use of communication tools I decided not to jump in early. After a short flurry of emails it was time for me to jump in. My comment was simple: "+1" In other words, they worked it out for themselves. Here is proof positive that the lead by example method works. We now have members of the community willing to take the appropriate leadership roles that I have carved out by being noisey and constructive.