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 dreamings, 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.

Today I removed a lot of packages from the package.json that were left there from furious experimentation. The whole thing is a lot slimmer now with a lot less dependencies. This pleases me.

Bigger than Commit Messages

When a developer is committing code to a repository, especially with a team, they will push their work as collections of commits. These have timestamps and a description. They are used to describe what happened since the last commit, so other developers can see the timeline of things unfolding.

The problem is that developers (myself included) make terrible commit messages, and worse, they are so far apart that it's not possible to describe the changes in a meaningful way.

What I wanted to do was talk in-depth about the things I had created, engineered or changed in a project. Something bigger than the commit messages.

In museful, when you create a new musing, your current branch, commit and username get stored in the file as well. We can then use this meta-data to build a website, rich with information, from a stream of musings I called, the timeline.

This can be done in any project with a package.json file. Any developers can contribute, at any time, thoughts about their work and their reasoning.

Since these musings are markdown files and they are now present in the source, the musings follow the source, and they are up for both peer review and consumption. Other developers can read your musings as they review pull requests.

They can also be collated into a simple blog type website and consumed by a wider audience, such as fanatical followers of your software.

Blogging from inside a project.

I hope this explains what museful is, but who can use it.

Who is this for?

Well, for starters, developers who need to talk about the parts of development they are currently part of. The challenges they have solved and the problems they face so that others might learn from their success or failure.

A tester might talk about the part of the application they are testing today, or scripts they are writing, or techniques they are using.

A business analyst might write about how the application is unfolding and the reasoning behind any features they require.

There is a lot of discussions and thoughts flying around during a project. Some of them can be used to guide the software, your team, or even the company.

So let's get them out of our heads, and into our repo.

I've spent some time refactoring the code for the various parts of the app. I've noticed in my excitement to get things working, I've made some serious spaghetti code.

If I was under peer review, this would not happen, but because this is a lone project right now, and I'm in dreamer mode, it happened anyway.

So let's go back and fix some of it.

Firstly, and perhaps most obvious is that there are too many nested and useless branching statements. It's if city here.

Then a few different ways of doing something, and I've made functions that do similar things in different files. Let's pull those into the same file, or at least make them unique.

There are few standards in error messages, in fact, two different types of error, so let us sort that.

Some of the CSS colours and theme designs and padding were not unified. Let's fix those.

There are endless ways to refactor code but at some point, you'll feel more comfortable and happier with the way it feels.

I've finally published the npm package of museful.

Heck.

When the template is built, we include some cdn hosted highlighting library.

Our markdown editor automatically wraps code in the correct html to make it all work.

    <link
      rel="stylesheet"
      href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/dracula.min.css"
    />
    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>

Beautiful highlighting!

In the museful editor, we use markdown. This means we can use the hashtag # to denote a title.

When the creator muses a document where the first line has a single hash, we assume this is the title and we set that in the metadata.

I think this is a nice quality of life feature, and this means that the markdown API returns the title, in the JSON response.

Bringing it all Together

I've taken a little break in coding museful, mainly due to the coronavirus pandemic that is gripping the nation, but now I'm back. I've bought myself a new keyboard, a mechanical one that makes wonderful sounds when I type, so typing is fun again! So let's get back on it.

A new theme is born from the one I created for plix, and I've called it committed.

git commit -m 'created a clever theme name based around a git command'

It's a rework in that it is stripped of all the social and other clutter, and I've made those elements present in the source HTML, merely commented out, for future template editing, when you may want them back in. It also includes customizable navigation and some fun header images and such.

It shares the dark blue of the admin theme, and this can be easily configured using the museful.json found in your musings folder.

Honestly, I hate using it, it seems to be outdated and hacky, but sometimes frameworks dont do updates immediately, and this is a require hack.

This time I needed to make sure the pane on the left where you type your markdown is always the height it should be even after you toggle the preview on, because it lengthens and shortes it based on the width.

That is all, rant over, everything is gravy.

Sometimes I find myself pushing my opinions of those who might use my software. In this case, I'm expecting them to write thoughtful musings on a project.

Developers need to be aware that, when you contribute thoughts to museful, you are actually putting them into the source repository and that these markdown files, though prepared in a web interface, will be checked over by your comrades for errors and omissions.

These files though, the thoughts, I want them to be less reviewed as enjoyed. I want others on your team to see your process while you were coding and learn from it, or even, disagree if that's their bag.

Either way, my opinion is that these are places for dreamers and idea people.

It's perfectly OK for developers not to contribute musings. I just hope they sometimes read them.

Flat files instead of a database

What I'm working on

I'm working on the API of museful.

I've solved a problem

Reading and creating markdown files in nodejs.

app.post("/musings", async function(req, res) {
  try {
    if (req.body.title && req.body.content) {
      const id = await createMusing(req.body);
      res.json({ status: "ok", id });
    } else {
      throw "title and content are required";
    }
  } catch (error) {
    res.status(500).send({ status: "heck", error });
  }
});

Lessons learned

It is possible to create an API that does not have a database behind it, but merely any other kind of store. In this case, I can CRUD text files that are in fact markdown.

We expose this functionality though a REST api, and it looks like we are dealing with a data service or some kind, but actually, its just files.

The Logo

I know that to connect with an application we use, and to have it become part of our ritual, we need something tangible to lock onto. I needed a break from coding for a while so I decided to put goether some colours and an art style for the project. I decided to make a sort of mini brand.

I thought about the way we think about the word muse and what it means. I don't mean the band Muse, although they are very good, I merely mean the inspirational types that give is direction and ideas when we are perhaps lost.

To me, muses are part of Greek mythology, and this is my original idea.

https://www.greekmyths-greekmythology.com/nine-muses-in-greek-mythology/

The muses

1. Clio: The Muse Clio discovered history and guitar. History was named Clio in the ancient years, because it refers to “kleos” the Greek word for the heroic acts. Clio was always represented with a clarion in the right arm and a book in the left hand.

2. Euterpe: Muse Euterpe discovered several musical instruments, courses and dialectic. She was always depicted holding a flute, while many instruments were always around her.

3. Thalia: Muse Thalia was the protector of comedy; she discovered comedy, geometry, architectural science and agriculture. She was also protector of Symposiums. She was always depicted holding a theatrical – comedy mask.

4. Melpomene: Opposite from Thalia, Muse Melpomene was the protector of Tragedy; she invented tragedy, rhetoric speech and Melos. She was depicted holding a tragedy mask and usually bearing a bat.

5. Terpsichore: Terpsichore was the protector of dance; she invented dances, the harp and education. She was called Terpsichore because she was enjoying and having fun with dancing ( “Terpo” in Greek refers to be amused). She was depicted wearing laurels on her head, holding a harp and dancing.

6. Erato: Muse Erato was the protector of Love and Love Poetry – as well as wedding. Her name comes from the Greek word “Eros” that refers to the feeling of falling in love. She was depicted holding a lyre and love arrows and bows.

7. Polymnia: Muse Polymnia was the protector of the divine hymns and mimic art; she invented geometry and grammar. She was depicted looking up to the Sky, holding a lyre.

8. Ourania: Muse Ourania was the protector of the celestial objects and stars; she invented astronomy. She was always depicted bearing stars, a celestial sphere and a bow compass.

9. Calliope: Muse Calliope was the superior Muse. She was accompanying kings and princes in order to impose justice and serenity. She was the protector of heroic poems and rhetoric art. According to the myth, Homer asks from Calliope to inspire him while writing Iliad and Odyssey, and, thus, Calliope is depicted holding laurels in one hand and the two Homeric poems in the other hand.

Poetry can't be written without a pen, and I love using a quill. I like the idea of code as a form of modern poetry, something we can share and read together, understand and learn from.

I wanted the brand to show this, and to call back to those muses, with a magical, ephemeral sort of glow.

Each of the stars and points around the quill, represents a differnet one of the nine muses.

I rounded any sharp edges, because that not what this project is about, its about stress free writing, and learning from the code-poems of others.