[WORKFLOW] BoST Open Source Workflow & Documentation Troubleshooting [2017]



Hey @BoST

I think we developed some issues lately in our workflow that need to be addressed. And I realized we never really spoke about our workflow. That is a problem. Let’s start a process. Here is how I see it:

##Open Source
In our blog you can read about the OSCEdays’ Open Source Workflow and all its benefits. Open source software projects structure their collaboration process in a way that it creates documentation in parallel – as a side effect – and in a quality that enables an outsider to quickly understand what happened when and why at any given moment. Timelines (threads) are one key to this. To have searchable tools another. Up to date Overviews a third.

Our workflow has fallen apart lately. We started to branch out into other tools. Some of them don’t work well in an Open Source workflow.

We decided to use our forum to try to do something similar for our project as the software/platform Git does for open source software projects. The forum is not perfect for this! True. We have to force it a bit and it will be a struggle. But the path we recently went to is much worse I think. Let me explain a bit my view:

##Documents – are bad
Collaborative documents like google docs are a bad tool for open collaboration! They become quickly very messy and can be only followed by those who have been part of the process from the beginning. Well unless you have a lot of time and nerves and you are ready to wonder, guess, search… for a long time. They allow too many options in color, size, formatting, deleting, commenting, commenting on comments etc. You can use a document for a quick task in a small team where you pull out a text afterwards and put it into another workflow. But for long collaborative development and collection or even discussions?.. Nope.

##Threads – are good
Threads on the other hand are a great idea!

  • You know always who speaks – who reacted to what. This brings context! Context is key. My teacher always said: Context makes meaning. Which is true if you think about it.

  • You have a timeline automatically! When happened what. This is a fantastic information that tells so many things – it is more context. In a google document the timeline is very very hard to follow, or impossible. The context is already missing. That makes it so hard for outsiders to make sense of stuff and add to it.

  • You know that the latest info/result is at the bottom. Go right to the bottom where the discussion ended. And if you have trouble to understand it you can scroll up and find out what happened earlier. Context and explanations is there – but only if you need it.

Because of this basic structure a thread is very accessible from the outside! It is already a good documentation. In a process that wants to include many different people on different schedules. Let’s develop things in threads \o/.

##ReadMe’s & Overviews
Of course a long discussion thread can become quite messy too. And if a complex processes branch out in many subdiscussions and subtopics it can be hard to find things. In this cases someone needs to make some time to create and maintain an overview. A ReadMe First. The overview gives context and collects links to subthreads. When the subthreads also link back to the Overview topic – then it is close to perfect.

Here are two examples from our forum:

This Overview topic is the go to topic for newcomers and also for the insiders! It is of course quite a task to create and update those Overview topics. It is work. But it is the best bet we have – I don’t know a better option. And it can be done quite relaxed. Just collect stuff in comments for a while before updating the main body.

If you want to get or share updates about a certain thing that overview topic is the go to place! Not some thread somewhere. Not a BoST call thread for example.

There should be a person in charge for each overview topic. It is a service to the community and a necessary thing for the collaboration. We had Overview topics in all categories for example here.

A maintainer should always think: If I get hit by a bus tomorrow and another person needs to take over my job it must be possible for that person to start right away because everything is documented so well!

This kind of documentation enables us to run the democratic project we want to run.

that is my opinion - I am happy about others

Actually this topic here is the start for the missing “Overview” or “ReadMe” topic about how we collaborate in BoST.

##Our Forum
Our forum offers a lot of great things like pinging people or pinning topics. You can subscribe or unsubscribe to categories. It is not perfect! But we can restructure it always.

I did not really understood why we moved to Loomio recently with some things. Loomio is basically also a forum but worse and less developed than our discourse (name our forum software). The only advantage Loomio has is that you can vote there which is not possible on our forum I think. We can go for that to Loomio or another online voting solution sure. But let’s have the discussion on our forum first – then create options and take them to a vote: link to that external place. And when the decision is made bring it back to our forum.

UPDATE: Apparently it is possible to vote in our forum too! See Sams comment below.

The problem with switching between tools is that you loose at least 50% of people on your way over.

##On The Phone
Some said it is hard for them to follow what is going on on the forum because they are phone people and they need something they can have on their phone. Well it looks like there is a discourse phone app. Can you try it?

Related: Complete transcriptions of what was discussed in a meeting do not make good minutes. In a meeting you spend a lot of time to get rid of misunderstandings, restate things and so on. The process takes time, it takes time to find solutions and understanding. If you only read the documentation you want the outcome and main points. Not all the little statements. You want to watch the game while it happens. But not afterwards – you don’t want to read though a description of it. You just want the results and a few numbers and scenes. You don’t want to watch the recording of a game after it ended. You want the results and some highlights and scenes.

Good documentation is first and foremost an attempt to protect other peoples time.


Ok. That would be my statement and view of how we should collaborate and progress our collaboration. Curious about your view.

[BoST Call July 31, 7 pm GMT] - 2017 - General Call #21
[BoST Call September 11, 7 pm GMT] - 2017 - General Call #24
[BoST Call July 17, 7 pm GMT] - 2017 - General Call #20
[BoST] OSCEdays Board Of Stewardship – About, Meetings & How To Join
[WORKFLOW] Forum Analysis / User Functionality [2017]
OSCEdays Framework Development 2017
[BoST Call July 17, 7 pm GMT] - 2017 - General Call #20
[BoST Call July 31, 7 pm GMT] - 2017 - General Call #21

Well, actually when you’re posting a topic, if you click on Options (the little gear icon on the right of the toolbar), you can choose ‘build poll’

You choose a type of poll, and type in the poll options, and whether or not to show who has voted in the poll:

Then people can vote on it.

Where do you think think OSCEdays decisions should take place?

  • OSCEdays forum
  • Loomio

0 voters

p.s. this is not some expert knowledge that I got from a lifetime of Discourse use - I read this post, then searched online for ‘Discourse’ and ‘polls’.


A relevant discussion thread from 2015:


I was just on the TransforMap forum and saw this relevant thread:

Three benefits of Loomio:

  1. Loomio allows all decisions that have been made be easily found in one place without becoming buried in the forum somewhere.
  2. The first benefit of Loomio that I have identified is that it is a public multi-platform option. This means that for me as a Loomio user and OSCEdays member (amongst other communities), even if I don’t participate deeply in the OSCE community but like to keep a broad overview of what’s happening on multiple community platforms (see image), I can go between numerous platforms from within Loomio. I think this has the potential to increase reach of decisions to more users and as per the previous thread on TransforMap also.

Here is an additional benefits that @transitionmaike pointed out in a another post:

  1. “also I find the calls fairly tedious due to the bad call quality and technical difficulties. For important decisions I would like to switch to https://www.loomio.org/ That way we can make sure the issue is framed in a way everyone understood, arguments are documented and we can set deadlines for the actual decision and know exactly what it is we decided to do. And all that without having to meet up at the same time from different time zones.”

Source: [BoST Call Mar 6, 11 am GMT] - 2017 - General Call #11


I have mentioned a few times to @Lars2i already that I am doing a systematic review of all of the forum content with the purpose of trying to understand how we can make it simpler to engage with.

I already have some clear insights on how I think the organisation of the forum could be improved, based on simple operational changes (e.g. inconsistencies in where content is placed, clearer signposting to the video channels, better ways to encourage forum good practice, such as systematically closing down threads), to higher level questions like: what is the purpose of the forum? Is it for us as a content creation platform, BoST workflow management, networking hub, or all three?

I will be finished this in the next week and will post my full feedback then on the forum. In the mean-time, you can see the development of this feedback in this document:


Is http://www.theblueeconomy.org/ worth considering? If “solutions” are what we decide that OSCE Days is about, an easy route there would make sense? With BOST type admin taking a few more clicks to get to?


Worth considering for what @seigorobinson? I don’t understand the question :slight_smile:


Once I’ve done a full review of the forum issues, I will make a set of proposal for improvements.

Reminder: A list of ‘newsletters’ in the same way that we have a chronological list of the BoST calls would be very convenient.


Sorry, I meant as part of the improved/simplified website/forum. The forum seems to be quite intimidating and looks “techie”. If we decide that OSCE Days is first and foremost a purveyor of OSCE solutions, then the first and most obvious thing to click on should be solutions (or even just a picture gallery of solutions).