I faced a problem. I think a complex problem since it involved: people, openness and IT. So an ideal mix for testing tools suited for complex problem solving. A simple description of the problem is:
How to get more collaborators for working on the next version of the ‘Open Reference Architecture for Security and Privacy Reference Architecture’ publication?
We, the current project members, think more people on this project is more fun and the content creation process for a new version will be increased. And before you read on: Everyone involved on this project will have the same rights and has the same benefits. We use the cc-by-sa license to make sure equal sharing is enforced. So this open writing project works like a pure GPL software project but instead of code, we create and harvest solid security and privacy information.
I like this Open Security and Privacy project, I really do. And with the aid of a very good security consultant this project became a real success! Almost everything we had in mind when starting this project worked out very well. To give you some insights, by doing this open security and privacy project we:
- Published our first version of this publication online in various formats (pdf, ePUB, html).
- We received a lot of very positive input from readers.
- Got invited for doing a great talk on an open source conference.
- Created a master class based on material and knowledge gained. Based on our experience as security architects/consultants in the field and by working on this project a lot of knowledge was collected that we wanted to spread. This because we think that more people and companies should benefit of creating better and faster security and privacy solutions based on solutions we provided in this publication.
- Enlarged and deepened our knowledge on many FOSS security and privacy tools.
- Learned every day by examining and collecting people and groups that work on open security and privacy tools, frameworks and publications.
So after the first success of our joined project we wanted more. So again we looked each other straight in the eyes and both of us wanted before 2016 was over: Update some content to create also a hard-copy version of our publication. And again our collaboration worked out very well: So the 2016 version of our work is now also available worldwide as printed on demand hard-copy on amazon.
As results of the fun and new knowledge acquired we set again a new goal for 2017. A simple goal. Before 2017 is over a more drastic update of this publication should be created. With far more topics and even more exiting references. And this is how we got into the problem of getting more collaborators that could easily on-board on our project. So how to solve this?
As architects do we start to think. Thinking is good, but too much thinking can and will slow you down. So we created some requirements and I did some experiments. First our simple requirements:
- The project should be open for everyone to join and collaborate in an easy way.
- In order to maintain the project solid version control is needed.
- The tool chain used for creating html, pdf, ePub and hardcopy versions of the publication should be as simple as possible. Yes as for all FOSS project counts also our time is limited since we have also bills to pay. This means that text and images should be easily convertible to various formats. Pandoc is the Swiss army knife for this.
- The entry borders for joining the project and on-board as collaborator must be as low as possible.
So with this requirements I tried to solve this complex problem in a simple way. This to avoid making working on this project a complicated task for future collaborators. Traditional collaborative writing projects need good tools. Tools needed should be split into three fields:
- Tools to write. Preferred is of course write content in the favourite editor of your choice
- Tools easily combine writing efforts of various writers.
- Publication tools. This to easily create pdf, ePUB, html and hardcopy version of text that is created.
So the needs are clear, however the field of open source writing tools that cover all three fields are hard to find. And when the tools needed are combined with our simple requirements a perfect solution seemed far away.
Traditional there are WYSIWYG text editors, like Open Office (MSWord alike). Real distraction free writing means do not mix typesetting with your text so creating publications using LateX is still done on many placed. Also the tool chain with LateX is excellent so creating PDF,ePUB or HTML is straight forward. However using LateX for the next version of our publication will certainly increase to border to join. I think in 2017 you should not ask people to create text with LateX unless you really hate them. Version control on shared collaborative text is nowadays easily possible with commercial tools like Google Docs or MSWord. But also FOSS online collaborative writing tools are great, like Etherpad or other NodeJS based tools. But since we are working on a FOSS project using commercial tools makes no sense. And hosting an own online environment will take some extra effort. So what are the main tools used by collaborative writing projects? I found that used by many is:
- Combination of git or svn (mostly github) with the use of simple markup language. Markdown, asciidoc or RestructuredText are mostly used.
- Some writing projects use Gitbook. Which is in basic just markdown with Github, but made a bit easier by fancy GUI’s.
- Some projects use some kind of a wiki. Own created wiki but mostly of course Docuwiki to keep things simple.
But I could not image that our project was the only project facing this problem! So a deeper search brought https://www.authorea.com/ . Searching more and deeper and looking to other collaborative writing projects did not give more input. Great collaborative open writing projects are out there. E.g. the new Drupal8 manual, the WordPress manual, many core BSD or Linux distributions have fantastic documentation created by many. But the issue with all is that the tool chain quickly becomes complicated and so time demanding for maintenance.
Playing with tools gives sometimes a very good and quick impression on how things work. After playing and experimenting with:
- GitBook
- Authorea
- DocuWiki
- Asciidoctor
I had a very good insight in what is simple, what requires minimal time and what really sucks. So I made a choice. Final. Enough time spend on finding the best solution for our problem. There is no best solution. Not now, maybe in future when some other FOSS project really tackles this problem.
So for the next version of our great “Open Reference Architecture for Security and Privacy” we will happily invite you to join our project. We use simple:
- Github for version control.
- Create text using RestructedText. RestructuredText has far better options than markdown. And is still really simple and plain.
So with these choices still everyone can work with the editor of his/her choice. We had of course serious thoughts on who is ‘everyone’. Who will be the users and collaborators of this next version of this security and privacy reference architecture publication? We think by making these simple choices we put a filter on who will join and who not. We know this. We think that for serious security and privacy minded people joining this project is dead simple.
To create a correction on spelling or grammar a simple pull request will do. You only need a github account, but when you are in security we think that it makes sense that you are familiar with the Github space. If you want to create new sections we prefer input within pull request writing in rst directly, but plain text is fine too. We will however set some basic collaboration rules to steer this project into the next phase. We will base this on the zeromq C4 RFC, but will tailor it to our writing project.
An extra advantage of development of our publication using git and RestructuredText is that we will also publish an online version on ReadTheDocs.org. So http://security-and-privacy-reference-architecture.readthedocs.io/en/latest/ will be used in future as the latest version.
Summarize: If you are a serious as security or privacy architect or designer you should really join our project to take it with is to the next phase! It will be fun!
And no: Still I think that this current workflow for this collaborative writing project is far from perfect. This because I like to use editors that I can use to write RestructuredText directly, but also offer direct grammar and spelling control.
If you like to know more on designing security and privacy solutions faster and better, do not hesitate to contact me.