###############################################################################

      *****************        Hey! Welcome to the Kwoosh Workshop
     *******************       -----------------------------------
    *******  *****  *****
   ********  ****  *******     This is where we talk about the things
  *********  ***  *********    we're working on.
 **********  **  ***********
***********     *************  Most things start as messy ideas before
 **********  **  ***********   they get polished into finished features.
  *********  ***  *********
   ********  ****  *******     This is a place for messy ideas.
    *******  *****  *****
     *******************       For the completed product see kwoosh.com
      *****************

###############################################################################
                

Making solid software

With our recent rewrite to Vue and a soft launch of Kwoosh, we’re finally able to use Kwoosh again. With any major rewrite or change you’re going to find bugs or other bits that didn’t quite work as intended. Often these bugs are just oversights in our implementation. We didn’t think about how to handle some detail.

In Kwoosh there are three basic types of users that will use the system: Anonymous Users, Users with a confirmed email address, and Users without a confirmed email address. Some pages in Kwoosh should only be visible to Unconfirmed users, for example the “please confirm your account” page.

To help us quickily and easily allow views to only be visible by unconfirmed users we made a simple view decorator in Python that’s used like below:

Once the code was in production we realzied we overlooked a user-class in our implementation: AnonymousUsers might hit these URLs too and we weren’t handling that case. My initial urge was to fix the bug and move on to more interesting features. Instead I ate my vegtables and decided to use our new testing setup and write some tests for our decorator.

It took me a bit longer to sit figure out how to minimally test our decorators than just fixing the bug itself. By iterating through possible solutions for the test I found some gaps in my initial fix.

The end result is better code, confidence that thie error won’t occur again, which allows me to rest easy knowing that if it crops up again, we’ll catch it before it gets to produdtion.

Getting into the habit of adding tests for every 500 that occurs in prodution is an excellent method to increase the quality and reliability of your software.

—jvd ~~~~~~~~~~~~~~~~~~~~

Artifacts of our work — what makers can learn from Edo-era Japan

During the Edo-era, Japan isolated itself from the rest of the world. All resources were precious. Re-use and recycling were the norm. Not because they loved and cherished nature, though that may have played a role with their Shinto backgrounds, but out of necessity. With limited contact with the outside world, Japan had to be self-sufficient. As a result, communities worked together to make sure that nothing went to waste.

Umbrellas were made of bamboo and paper. Once they started showing wear and tear they were refurbished. The bamboo was repaired and new oil paper was attached. The old paper was sold as packaging material.

Starch extracted from rice was used to repair ceramics. Human waste (night soil) was bought by farmers and used as fertilizer in their fields.

This kind of reuse of by-products was a part of life in the Edo period and the effects still reverberate in modern Japan. Letting excess go to waste even has its own word in Japanese: “mottainai”.

While we aren’t usually concerned about letting excess go to waste, mottainai is uttered on a regular basis in Japan.

I’m helping bootstrapping a product to manage software products called Kwoosh. Kwoosh will make make product management easier and more efficient for small agencies and developers.

Building this product made me realize how much of the work involved isn’t writing code. Phone calls, mock ups, chat history, design: all of this lost in time or hidden in a folder. Valuable artifacts just thrown away.

All of these discarded artifacts of work can be reused and re-purposed, so as to not be so mottainai. What if we tried to save them? Could we make something valuable out of ‘trash’?

Phone calls discussing product design and decisions can be turned into podcasts. Libraries written to help us power Kwoosh can be open sourced. Mock ups shared to illustrate how we do product development. Core ideas and philosophy from all of these artifacts can be broken into articles helping us solidify and codify our values.

What artifacts are you generating from your work and how can you reuse it?

—jvd ~~~~~~~~~~~~~~~~~~~~

Remove as much code as possible

One of the benefits of moving Kwoosh over to Vue and an API backend is that we have managed to remove about 25% of our code base.

Whilst lines of code is not usually a good metric to use for anything. The count shows us that we now have less code to test and maintain…which is a huge win.

Every line of code that you don’t write or can remove is one less line to manage.

Lines of code

—jw ~~~~~~~~~~~~~~~~~~~~

Apps vs projects

The words you use in an interface can dramatically alter your perceptions of it. Words can make it feel cold and stern, or warm and friendly. They can encourage you to write longer responses or none at all.

This is why with Kwoosh we thought long and hard about what we should name our primary object. In most project management software the term “Project” is used. The first thing you do is create a project and then enter data into that project and so on. You then however complete a project.

With software however, things are never really complete. Once software is written it’s usually not finished, instead it moves to the next phase of its lifecycle…maintenance.

Because of this we didn’t like the term “project” as we feel that projects are things that you start and finish. We therefore choose to use the term “App”.

App is short for application…which is what you build with software. They can be desktop apps, mobile apps, web apps, server apps etc.

But more importantly we feel that apps doesn’t imply that it will finish. Once you finish writing your app you have a completed app to release and maintain, as well as the Kwoosh resource of all the info about your app and how to maintain it.

—jw ~~~~~~~~~~~~~~~~~~~~

No feature deploy without writing

In order to keep writing more and talking about Kwoosh. We have decided that we won’t deploy any new feature without first writing about it.

When designing and coding new features we make hundreds of tiny decisions and compromises and we want to write about them more. This workshop is here so that we can shed more light on the design and building aspect of software…so having a mantra to follow should get the ball rolling and have us write more about the small details.

—jw ~~~~~~~~~~~~~~~~~~~~

The fog of building

When you’re working on a project day in and day out, it’s sometimes hard to see the big picture. You get lost in the haze of minor details and the search for perfection. For the past week or so I’ve been lost in the fog.

It started after we managed to soft, soft launch Kwoosh. It had been a hectic week getting everything finished, and then the relief of releasing started to turn into the dread of iterating.

What you had thought was a finished job and good enough to launch, is actually more of an embarrassment, and you see issue after issue and tweak after tweak. This leads you to then continue to slog away on stuff…until you end up lost in the fog.

In the fog you lose your extended vision and so without careful attention you can start to wander off course and get lost. You aimlessly chase after little bugs or sharp edges and before you know it you are going around in circles and not getting any closer to your goal.

The solution is to stick to path you were on. The fog will eventually lift and you will get clarity again. But whilst you are stuck in the fog you have to stick right on the path and have the faith that it will bring you out of the fog to the destination you originally intended.

—jw ~~~~~~~~~~~~~~~~~~~~

Things you need to do to start a project

Things you don’t need

—jw ~~~~~~~~~~~~~~~~~~~~

Things you don’t need to do to start a project

Things you do need

—jw ~~~~~~~~~~~~~~~~~~~~

We soft, soft launched

63 days and 759 commits later and we finally merged our development branch back into master and soft, soft launched.

We will now spend the next week or so just testing things out and checking that everything is running in the way we want it to on the production server before opening things up and allowing people to start using it.

Our development branch before merging

—jw ~~~~~~~~~~~~~~~~~~~~

Scratch your itch

People don’t talk much about building for themselves these days.

Read this article and learn the secrets of writing your own articles to attract people to your website.

You can’t build anything until you’ve setup a landing page, interviewed 100 people, and have 1,000 true fans to send an email to on launch day.

Forget writing software products, take my course to teach you how to build your first product (hint, the product is not software, it’s a course).

Bullshit. 

When was the last time Apple setup a landing page and decided to scrap an idea because they didn’t get enough signups? Never.

Or Edison? “Didn’t get enough sign ups for the “lightbulb”. On to the next idea.

More people signed up for the faster horse service, guess nobody wants a car.

Hogwash.

Build what you need. Scratch your itch. Iterate. Improve. And tell people about it.

—jvd ~~~~~~~~~~~~~~~~~~~~

Technology compromises experiences

When we focus too much on development tools and technology it can cause us to compromise on our user experience.

Rather than using the right tool for the job, we use the tool we’re used to or some the new fancy tool we keep on reading about.

To help combat this I’ve found it best to ask myself for each and every screen the following questions:

The fixes don’t need to be made all at once. It’s often better not to.

We find it better to think of improvements, plan them out a bit and revisit it a week or two later to make sure it all still makes sense.

—jvd ~~~~~~~~~~~~~~~~~~~~

Reworking workflows

Recently I’ve been re-working our Add App flow. This is the first step of any project.

It’s a two step process: enter the app details (name, description, and so forth), and select who should have access to the app.

Users can also have access to multiple accounts, for example a freelancer working on his own projects and also using a customer’s Kwoosh account for their projects together.

If you have access to multiple accounts and you’re adding an app we need to know who it belongs to, so we show a drop down letting you select the proper account.

Setting the account on this first step really serves two purposes:

  1. Tells us who the app belongs to so your team can access it, and
  2. Let us populate the second screen with the users from that account.

Because Kwoosh was rendered on the server and we had minimal front end processing abilities, two steps was mandatory.

We had to send data back to the server in step one so we could display data in step two.

With our rewrite we have a lot more flexibility and we’re able to cut our flow in half, to just a single screen. A huge win.

—jvd ~~~~~~~~~~~~~~~~~~~~

Don't throw it away

When building a product when things don’t quite work as smooth as we want, it’s tempting to throw it all out and start over. Don’t do that.

Starting from scratch lulls us into a false sense of security that we we won’t make the same mistakes that we made last time. While that may be true, we will make different mistakes.

It’s better to refactor. Change one bit of functionality. One screen at a time. This will let you make things right over time and keeps you with a functioning product.

You also don’t have to face an empty project.

This is what we’ve effectively done with our Vue transition in Kwoosh. We’ve rewritten the majority of the code base and things are much cleaner, faster, and maintainable. I don’t know if I could have done it if we had throw it all away.

—jvd ~~~~~~~~~~~~~~~~~~~~

Thoughts on navigation

As with all things in software design, it’s always a good idea to sit down every so often and think about the purpose of that one thing. Let’s have a think about navigation.

A lot of the UI of Kwoosh is navigation. We have a masthead with notification and user data. A sidebar with apps and more popover navigation. Breadcrumbs. On-screen links. Page navigation. Etc.

Kwoosh navigation

Navigation should be like oxygen, you don’t notice it until its not there.

Recently I’ve visited a few major sites and have been struck at the lack of navigation and found myself having to use the back button to get around. If users are having to use the back button as a primary method of getting around your site you have seriously messed up.

So what we have tried with Kwoosh is to add in a lot of redundant navigation. Everybody uses software differently and so providing different ways to get around allows everybody to find their feet and navigate in a way they feel comfortable.

Kwoosh navigation

—jw ~~~~~~~~~~~~~~~~~~~~

When in doubt, choose consistency

There’s a lot of things that go into making great software, but one of the main things is consistency.

It’s not a very sexy topic to talk about as it seems so basic and obvious…but it’s one of the hardest things you can do and takes time and patience to do right.

Consistency should be everywhere in your software.

In your code. Variable, method and class names should be consistent and follow a naming convention. Tabs vs spaces. Capitalization. Location of files. Formatting styles.

In your design. Navigation should stay the same. Fonts. Text size. Color palettes. Layouts. Forms. Messages. Alerts. Popovers. Links.

In your words. Things should be phrased in the same way. Names for sections or actions should follow a rule. You shouldn’t use ‘delete’ on one screen and ‘remove’ on another.

For all of these things, it doesn’t matter what the thing is…but that it’s consistent. So it doesn’t matter if you use tabs or spaces, all that matters is that you use the same thing all over.

—jw ~~~~~~~~~~~~~~~~~~~~

Deployment, deployment, deployment

One of the first things we did with Kwoosh was to build a pretty robust deployment process. It was probably a bit of an overkill at the time, but it was a fun project and a new challenge to throw ourselves into.

When starting the Workshop I copied a lot of the deployment process over, so lets take a look at how this site works.

The Workshop is a statically generated site using Jekyll. This means that its just a bunch of simple HTML files and a few images. There are no complicated databases, frameworks or scripts…at all.

We begin the process of writing a new post in a text editor and Markdown. We write simple posts that reflex our design and ethos and then commit them to a git repo. This is then where the magic happens.

Whenever we push commits to our master branch a web hook pings our deployment server to let it know there is something to do. Our development server runs Jenkins and this receives the ping and gets to work.

For all our deployment processes we have three stages. Build, test and deploy. We therefor have three jobs with these names within Jenkins that are run in that order.

The three job stages within Jenkins

For this site we only use Jenkins to call an Ant script where most of the work is done, and this also follows the three stages of deployment.

Build

In the build stage we build all the resources we need for the website.

Primarily this means that we call Jekyll and that spits out all the HTML files for the website. We then run our CSS through a linting process to check for errors and then minify it. If we had any JS we would also do the same at this point.

Finally we run all the image assets through a minification process using a series of different command line tools for each image type. This removes any un-needed data from the image files and reduces their file sizes…by up to 40-50% in some cases.

We then move all these files into a build directory so that everything is nicely organised.

Test

Normally we would then run a series of tests against the content in the build folder. We don’t yet have any for the Workshop, so this step is just skipped.

Deploy

If the tests all pass (which they do) we then begin the deploy process.

For this website that means uploading to Amazon S3. We use s3cmd to sync the HTML files to one bucket and the assets to another. It then invalidates the CloudFront cache, and after about 30 seconds and a refresh the new content appears on the site.

The whole deploy process takes about 15 seconds to process and then another 30 or so for CloudFront to start serving the new content.

And that’s it. All we have to do is write and commit. No messing around with FTP or updating Wordpress. We commit and go.

Successful deployment shown within Slack

—jw ~~~~~~~~~~~~~~~~~~~~

Accidentally created an API

Over the past few days I accidentally created an API for Kwoosh.

It started out by thinking about how a delete link should work, and ended up by cleaning up a lot of code and making things both simpler and more useful.

We probably won’t tout the API itself, but we will use it for the front end of Kwoosh and in theory a user could use it to create their own apps.

Once we decided to do a RESTFUL delete request, the easiest way to handle it was to create a method for each allowed HTTP method per view. This then soon grew to remove the non-RESTFUL endpoints we had and merge them into a REST friendly environment.

It then turns out that the rest of the work we have been doing to move to Vue.js, allows us to easily select just the response data to return. And with that we have an accidental JSON API.

—jw ~~~~~~~~~~~~~~~~~~~~

When things just click

We have been on a roll with Kwoosh lately.

Changing lots of stuff and making it simpler and easier to manage from both a user and developers point of view.

This week everything has just started to click together. All the generic views and classes have been completed and implementation has been a breeze. We have gone from having to think about what we are coding, to copy and pasting code into the views we want.

All of a sudden the mentally hard work has finished and we are completing ten plus pages at a time and everything is clicking into place.

—jw ~~~~~~~~~~~~~~~~~~~~

Remove all the friction

I’ve had a post written for the workshop for about two weeks now. I haven’t posted it yet as I wanted to add images. It would take me 10 minutes to take and upload the images, but I’ve been putting it off.

This one little thing of adding a few images has added enough friction to publishing the post that I’ve put it off for weeks. I could (and probably will) just post it without images, as done is better than perfect and not done. But that tiny bit of extra friction has stopped me in my tracks.

Next time you find yourself stuck, try and see what is creating the friction and if its not critical just remove it. Remove all the friction and see how fast you can get things done.

—jw ~~~~~~~~~~~~~~~~~~~~

But does it help your users?

A large part of developing great products takes place by curating your taste for what makes a good product while you build it. A shortcut to build this taste it to constantly be looking at the software we use with a critical eye and asking ourselves why did they design this the way they did, and more often than not, asking what the hell were they thinking.

The easiest mistake is to avoid is to including too much information or irrelevent information on a screen. Often we include information almost sub-consciously. We saw a competitor do it, so we automatically assume we need to do it too.

For example let’s say you have a conference cataloging website and you want users to view and attend more conferences. When they view the details of a conference, how do you decide what to display, if anything, after actual conference details?

Does it make sense to show a “Recently Viewed” or a “Related Conferences” list?

The answer is not one or the other. The answer is to look at this from the perspective of what is your goal for users on that page in that work flow?

If the goal is to get users to browse more conferences so you can hopefully sell them more conference tickets, then it makes sense to show them other conferences.

If the goal is to find more information about one specific conference then sending them off to other conference detail doesn’t help them at all. Would a map of the conference, a list of other people attending, or previous year’s talk videos be more valuable?

Then think through any technical aspects. Can you show good enough related conferences that would actually be of use to people? Just because I’m looking at a python conference in New York…does that mean I’m interested in one in Texas?

Documenting your goals for each screen helps focus you on the core purpose of the screen and helps you from adding unnecessary information.

—jvd ~~~~~~~~~~~~~~~~~~~~

The hardest part

People say that programming is hard. But it’s not. Programming is easy.

What’s hard is figuring out what you need to do to make your idea a reality.

Breaking down the idea into a specification. Designing the data structures. Planning an interface. It’s all difficult work and requires great concentration and consideration.

As you implement your program you’ll inevitably find edge cases that you didn’t plan for or as a result of a requirement change.

The hardest part about programming is admitting that your plans, the ones you spent so much effort and time on, didn’t hold up to the requirement changes and then doubling back to fix it.

—jvd ~~~~~~~~~~~~~~~~~~~~

Changing posting habits

I go through spurts of writing new posts for this workshop.

I’ll have a single night of inspiration and write four or five posts, and then do nothing for the rest of the week. In the past when I’ve had these inspirational periods I’ve scheduled the posts to be published over a period of time rather than all at once.

It seemed a good idea not to throw too much content out all at once. It would give the audience a chance to read it all before new posts were published. The website would also feel more active with new content every few days, rather than a bunch of posts one day and none for weeks.

But with this workshop I think that is the wrong mindset.

We don’t care about numbers, so why should we be doing stuff to specifically try and get readers to come back more often. We are writing for ourselves, so we should also be publishing for ourselves.

So from now on I’m going to try and break my habit of wanting to spread out posts and just publish them when they are done.

—jw ~~~~~~~~~~~~~~~~~~~~

Not telling anybody

We have yet to tell anybody about the Workshop.

A lot of people start projects and then give up on them. We are no different. So we didn’t want to announce or link to this workshop until we had built up a little momentum and posted 20 or so items. That way we might start to form a habit of posting stuff here, and not just give up after a week or two.

Doing it for ourselves and not others I think has really helped. It’s taken away the pressure that comes from putting yourself out there, and has made it more enjoyable to just drop into a text editor and write a quick post here and there.

—jw ~~~~~~~~~~~~~~~~~~~~

But can they understand?

When we’ve been designing Kwoosh, we’ve aimed for an interface that’s both minimal and easy to use. Striking that balance can be tricky. Minimal interfaces often look cleaner in a screenshot, but are a travisty for users that are unfamiliar with how it all works (Even after writing 10+ posts on Medium, I still had to lookup keyboard shortcuts for all but the most basic operations).

A common mistake designers make is removing text in favor of color. A splash of red or green looks so much better in a screenshot, how does it work?

Can a first time user glance at interface and know what green means? What if your user is color-blind, can they even see green?

This said, it may sound like we’ve made a mistake with Kwoosh. After all, the main way customers categorize tasks in a single list in Kwoosh is by color: none, red, orange, yellow, green, blue, or purple.

The difference is that we don’t assign any specific meaning to any color. Color means whatever you want it to mean. You’re not stuck with our vocabulary when talking about your work.

kwoosh task list

—jvd ~~~~~~~~~~~~~~~~~~~~

Tweaking it all

With the change over to Vue, it has allowed us to go back through our code base and wonder what the hell we were thinking over the past 18 months.

There is a lot of left over legacy code from change after change as we were building the system and trying different things out. We now know exactly what we want and how they should work, so its a great time to go in, clean things up and stick to a single coding standard.

It’s a great feeling to remove a bunch of code and to simply things. Hopefully by the end of the switch things will be much simpler and easier to maintain going forward.

—jw ~~~~~~~~~~~~~~~~~~~~