I am still experimenting with posting research, from drafts through the editing process, on GitHub. No promises that we will keep doing this – it depends on the reaction we get. From a workflow standpoint it isn’t much more effort for us, but I like the radical transparency it enables.
I just posted a second paper, which is still very much incomplete. I want to offer some instructions on how to edit or propose changes. This is just quick and dirty, and you should review the GitHub Help to really understand the process.
GitHub is meant for code but works for any text files. Unlike any other option we found, GitHub offers an open, transparent way to not only collect feedback, but also to solicit and manage direct edits. Once you set it up the first time it is pretty easy – you subscribe, pull down a copy of the research, make your own edits, then send us a request to incorporate your changes into our master copy. Another nice feature is that GitHub tracks the entire editing process, including our internal edits. For transparency that’s sweet.
I don’t expect many people to take advantage of this. I am currently the only Securosis Analyst doing it, and based on your feedback we will decide whether we should continue. Even if you don’t push changes or comments, let us know what you think. Here’s how:
- We will post all our research at https://github.com/Securosis. Right now I still need to move the Pragmatic Network Security Management project over there because I was still learning the process when I posted that one. For now you can find the research split between those two places.
- If you only want to leave a comment you can do so here on the blog post, or as an ‘Issue’ on GitHub. Blog comments can be anonymous but GitHub requires an account to create or edit an issue. Click ‘Issues’ and then simply add yours.
- If you want to actually make edits, go for it! To do this you need to both create a GitHub account and install the software. For you non-command-line types, you can download official GUI versions here. If you are running Linux
gitis probably already installed. If you try to use the
gitcommand under OS X 10.9 Mavericks, the system should install the software if necessary.
- Next, fork a copy of our repository. Go to https://github.com/Securosis, click the Fork button, and follow the instructions.
- That fork isn’t on your computer for editing yet, so synchronize your repository. This pulls down the key files to your system. On the web page click “Clone to Desktop”, it will launch your client, and you can choose where to save the fork.
- Edit away locally. This doesn’t affect our canonical version – just your fork of it.
- When you are done, commit your changes in your desktop GUI by clicking Changes, then Commit and Sync. Don’t forget to comment on your changes so we know why you submitted them.
- Then submit a pull request. This notifies us that you made changes. We will run through them and accept or decline. It is our research, after all.
This is all new to us, so we need your feedback on whether it is worth continuing. We know many of you might be interested in tracking the research but not participating, and that’s fine, but if you don’t email or send us comments we won’t know you like it.