Online #KnowledgeManagement - audit and suggestions for change #knowledgemanagement
Following from Chris's post here, this is my audit of existing Bonsai communication mediums. Plus suggestions for changes that I'd like to open for comment before taking action which affects everyone.
The goal of this effort is to organise the Bonsai mediums such that interested people can quickly navigate to the most up-to-date information which is relevant for them. This way they are more likely to properly understand the project without unnecessary struggle. Once they have this understanding, their path toward meaningful contributions should also be clear. This is particularly important with the recent flurry of activity and upcoming outreach.
Bonsamurais organisation (17 members) containing:
· 4 repositories
· A top-level project board made my Chris today but not yet used
· main (24 members)
o hackathon2019 subgroup (16 members – note that posts here won’t necessarily reach the 8 people exclusively in Main)
· A 'company' (59 followers)
· A closed 'group' (339 members!)
o "About this group" is the only publicly visible part. It does not include links to other open Bonsai mediums
· static pages
· some document hosting here.
· Fairly detailed descriptions of planning and strategy
o it's not clear whether this or the wiki pages are authoritative on this topic, and there’s much duplication
· web-app hosting on this domain suggested
Root and subfolders shared with various email addresses; anyone with the link can edit. Subfolders:
· ‘documents’ - 8 sets of minutes from Developer and Board meetings
· ‘classifications and correspondences’ - 24 Google spreadsheets
https://bonsai-open.slack.com for chat
· Chris has stated he intends to also upload the chatlogs from the public channels for transparency
· Private channels can be used for private comms
Other currently planned mediums
For video calling/conferencing.
· Bo has a paid plan and has requested he be contacted for scheduling
· Zoom can be integrated into Slack for video meetings (but hasn’t yet)
Previous funding applications. These could be useful for potential future applications.
· The wiki becomes the primary destination for up-to-date information, with only stable information on the website (plus eventually the web-apps)
· Use the Github 'Projects' functionality for task management.
o When tasks relate to specific repos, use the 'projects' in those.
o For higher-level tasks or ones that presently lack repositories, use the top-level Bonsai organisation 'projects'
1. Update the wiki front-page (or make a dedicated page) with the outcome of this discussion.
a. use this as the general "contributing guidelines" (or similar) for the organisation. Stating how we agree to use the various comms mediums and tools such as GitHub Issues etc.
b. This becomes the basis for the #GettingStarted guide referenced by Chris
2. Update LinkedIn (group and company) descriptions with a prominent link to the Wiki front page
3. The Google Drive and website meeting documents are hosted for posterity as pdfs at a single location (I suggest the website only, as they are static)
4. Delete the copies from other locations
5. Add previous funding applications to the same location.
6. Add any missing information from the website-hosted strategy and work plan to the wiki. Then delete these webpages
7. Add a link to the Groups.io mailing list in the website contact section
8. Edit the ‘Status and statutes’ section:
a. ‘Status’ implies up-to-date: hence reference the wiki
b. ‘Statutes’ are static: with other website-hosted documents
1. The LinkedIn group is not open. Is this by default or is there a rationale for requiring an invitation before people can join?
2. Paid 'Membership' is currently only emphasised on the website. Should this option be made more prominent elsewhere?
I think this is a great start - I hope that you and a few others can put together a detailed plan including a repo with separate pages for what the website could look like, as well as a guide for newcomers, so that we can get to group consensus.
One small clarification - Sphinx is a tool to convert documentation from one format to another, for example to convert the Brightway docs from restructured text to HTML. It isn't a communication tool per se.
Thank you very much for this summary and for proposing those action points Tom.
NOTE: The fee and the cases in which the fee might be waved for contributors will be discussed at the next board meeting (next week).
About the action points:
Michele De Rosa
I had a very nice talk today with Oleg Lavrovsky, who makes his living as an independent open data consultant (https://datalets.ch/). He organizes most of the open data hackathons in Switzerland, and is active in sustainability data as well, so I think his feedback is worth listening to. Here are the points I noted:
We desperately need a getting-started guide - this should be the first thing one sees, after the small motivation section. We want to communicate from the beginning that each visitor has something to contribute, and that we need their contribution.
As a part of this getting-started guide, it would be worth building a sort of toolbox for beginners to bonsai, like the one found here: http://toolbox.schoolofdata.ch/. The idea is that we will have a bunch of people looking at our site who aren't experts in coding or semantic tech, but who are motivated to participate. If they see a wall of complications, they will just close the tab and move on, but if they have a list of tools with good docs and tutorials that will give them a chance to start contributing in a meaningful way.
In his experience, hackathons work best if there is one focus. In our case, I think it is worth re-emphasizing that the goal of the hackathon is to have a complete working demo that we can show people, and it probably makes sense to focus on getting the existing work packages to be good instead of starting a bunch of the stretch goals (though I have been dreaming of a bunch of BONSAI components: https://chris.mutel.org/bonsai-components.html).
He felt that the hackathon was a good opportunity to already involve more people online, and that there would be an audience if we did more outreach. Online participants need to be able to work independently, which means that we should have some example small projects that people can just claim and work on.
As a follow-up to this, I think it would very good to have a list of projects where we need help - this would allow people to either pick a project, or to get a sense for the kind of projects BONSAI works on, so that they can define their own. Here are some examples I can think of:
A key to hackathon success is to make sure that everyone can make meaningful contributions. Each person should be a champion or leader of their task/deliverable. Key here is fostering a positive and welcoming atmosphere, and being flexible as groups evolve.
One idea that was new to me was to have a data-driven hackathon, where we would be measuring data about the hackathon itself. Oleg and his team have developed https://datalets.ch/dribdat/, and though it is difficult to explain, it is quite cool to see in action. He would be willing to set up an instance for our hackathon.
Finally, we only get one chance to make a first impression, so all our communications should reflect and emphasize our core values, especially our embrace of openness, both in consuming open data, and in making our data available for others. We want people like Oleg to see our website and feel at home, knowing that this is a place where he could make a difference. It isn't easy, which is why we need to start ASAP.
I see that Oleg has joined our list, so he is welcome to add/edit the above points :)
The draft getting-started guide is here. It currently describes how I perceive the state-of-affairs to be now (regarding task management, prioritisation etc.). As such, it is not really yet fit-for-purpose. I don't yet know how to contribute toward simple, manageable, useful tasks. So describing this is rather difficult!
In order to be most useful, Romain & I agreed that we want the getting-started page to link directly to specific tasks. But we find those tasks are described in various places in different ways (Wiki, website, hackathon agenda, blog posts etc.). So we realised that this needs to be solved in order for the Getting Started page to function properly. We agreed that GitHub issues are a sensible choice for this. I've dogfooded a suggestion to use them for Bonsai here. And started converting the Wiki task list into Issues in the same repo. An issue relating to completing the getting-started guide is also here.
Other suggestions such as "a sort of toolbox for beginners to bonsai", are beyond my reasonable scope at this time. Great if someone wants to make this, but perhaps tangible Bonsai software contributions could be a higher priority!
I created the beginning of a BEP based on Tom's audit here: https://github.com/BONSAMURAIS/enhancements/blob/bep4-communications/beps/0004-bonsai-communication-strategy.md. My idea was to make our ideas a bit more specific by using the BEP to provide details, and also to make us think about alternatives and why we are confidant that one direction is best. However, we can continue to use the #KnowledgeManagement tag, as the BEP is nowhere near ready.
For example, I am not sure why the wiki is the best place to host a getting started guide, or general introductions to B. The webpage not only gives us more freedom in terms of what we can show (no limits on embedded media), but I don't think the wiki provides a substantial ease of use advantage versus e.g. writing markdown and having an automatic processor to create HTML.
Some of these issues are most easily discussed in person, around a big sheet of paper, where we can draw different designs. For example, I don't see why the homepage wouldn't have a little search box allowing you to search to ontology/product list, as well as a dynamic widget that would allow you to do calculation based on the current database state. That would be awesome, and a clear differentiator with other DBs - but impossible on the wiki.
I would prefer to get a clear line between what content goes on the wiki, and what on the web page.