museful project blog software

Idle Hands

Developers who love their craft, with free time on their hands is a dangerous thing.

They make things. I've made something to enhance the third way.

The Phoenix Project book has the three ways, to mindfully collate DevOps:

• First Way: Work always flows in one direction – downstream
• Second Way: Create, shorten and amplify feedback loops
• Third Way: Continued experimentation, in order to learn from mistakes, and achieve mastery

How?

I have put together multiplayer blog software that sits in a project.

1 Project = 1 Blog

If a project is stored in version control and developers contribute code that is peer reviewed then chances are your peers read contributed code and suggest fixes, changes and offer advice on better ways things might be done. In a good team, this is pivotal to keeping a project in line.

Sometimes, the conversation goes

• Developer: 'I have made this fix'
• Peer: 'This is not the correct way to do this, please fix'
• Developer: 'It should stay as it is because of this reason'
• Peer: 'I understand, please leave it the way it is'

But what if it went like this?

• Developer: 'I have made this fix and here are my reasonings and logic, here are some diagrams that explain the flow and the fixes I tried before arriving at this solution. Here are some links to help you learn the things I learned.'
• Peer: 'I understand, and I've learned something new today'

So how do we achieve this?

Making software is documented all over the place, all the different strategies, and techniques, all the languages, and methodologies.

They all share a commonality, and this is, the source code, is stored somewhere. The code that builds the product. It's either compiled, or it runs just in time, or a mixture of both. One thing is for certain, you keep it in git, or subversion, or mercurial.

Sometimes you even work as a team on the same project, or a project owner is a lone warrior.

If you work as a team then you could do peer reviews. Whatever your version control system calls it, when you want to merge your code into somewhere meaningful, people would inspect it for errors and issues.

This isn't something new, it has been this way for a very long time.

When code is committed to version control, you usually comment on what you did. Me? I'm terrible at this. My comments are brief and don't cover all the points, mainly because for some reason, pushing the code up there is just some time-consuming punishment, or something let over to do after the meat of actually writing code.

So what might happen if I had more space to write, and that writing something was a ritual, and something meaningful that I know more people might read?

If I knew that the things I might write would be taken in by others and that real worth might be derived from my thoughts as I code it's possible I might be inclined to share my thoughts, ideas, and discoveries, as well as failures.

If I know they would be useful.

Commit messages are not enough for me. I want to show you images and diagrams, I want to show you HTML snippets and a clever function I used.

Where is the place for that? A wiki? Confluence?

These are places outside the project. They are disconnected by being in separate systems. No, I need something inside the project itself. I want to keep my discussion, my dreaming, with the project like a treasure trove for further engineers to discover, or even share my revelations with the user, so they can see my insights and the reasons I did this thing, this way.

I created museful for this.

museful is a terminal application written in JavaScript. You can install it trivially with NPM, and it will help you get the ideas out of your head and into the minds of other dreamers.

It provides a browser interface to both reads and creates text documents, formatted with markdown (and HTML) that live inside your version control repository. When you commit your code and submit a pull request, your new thoughts will be alongside the code. People will be able to read why you did something this way.

museful provides a way to build the musings into a web site, that you can deploy any place you choose (or simply don't, it's your call). You can make your team's skills and ideas public, to excite fanatical fans. Keeping users in the loop is a very powerful tool.

museful has a load of clever features like theming and markdown previews and all that, but it's all down to the idea, that this 'blog' of sorts will run concurrently with your source code. We even tag the musings with the current branch and commit hash. This timeline will stay with the software. I hope this explains why I made museful and why I want you to try it in your project. Set aside sometime before your pull request to write about what you did. Maybe somebody might learn something from you, and this is amazing.

TL;DR: You need to keep a timeline of WHY developers did the things they did as well as WHAT they did, in your project so people in the moment and people in the after can learn from them.

Try museful in your next big project and ask people to share the why.