Blog of Rob Galanakis (@robgalanakis)

Being amazed by software development

I am continually amazed by the state of software development. I am amazed at how broken things seem to be, and I’m amazed at what powerful tools we have to fix things.

A few weeks ago, I struggled to find a documentation hosting solution. We have an internal version of Read the Docs which took far too much effort to get set up (dependency problems, creating a new SCM backend) and administrate, but Read the Docs doesn’t work with private Github Repos. After some hacking, we still couldn’t get it to work. So I looked at, which promised to host our docs in the cloud, but was totally broken. I looked around at other solutions and was tearing my hair out. I was amazed that no good solutions already existed, and was more amazed that the best solutions are somewhere on the spectrum of broken (no offense here to RtD).

At the end of the day, it occurred to me my use case was incredibly simple: just provide an index page for (already generated) HTML documentation. Let people POST their HTML files and some metadata, and just dynamically generate the index based on what’s available. I was going to run this behind a firewall, so I didn’t need to worry about security. Hell I could even get away with no database, and just read the filesystem.

The next day (a Saturday), while my son and wife napped, Host the Docs was born. It took 1.5 hours to create an initial working version, and then I spent a few hours here and there polishing things up. It was painless to deploy, and I did some more improvements after that. Throughout this experience, a few things struck me:

  • I’m amazed by frameworks like Flask and Bootstrap. You can create a reasonable site in no time that is totally maintainable. At no point was I “hacking” to get something up and running, it was instead a very small first version I was able to iterate on.
  • I’m amazed by Linux. I have to use Windows at work, but feel like I develop faster on my Linux Mint netbook as I do on my Windows 7 workstation. The power at my fingertips is divine. It makes me mad at Windows.
  • I’m amazed how well some software works the same way I’m amazed at how broken some software is. Software is truly evolving; for every Flask, there are confusing and broken web frameworks.
  • I’m amazed how much time having autonomous teams can save. It would have taken a day or more to deploy HTD if I had to go through IT to provision a normal virtual machine (I doubt that frustration is unique in our industry). Instead, by giving teams an AWS budget and not centrally controlling things, HTD was live in minutes.

I’ll post more fully about Host the Docs later. I just wanted to express my satisfaction before it wore off :)

(BTW, I’m aware how similar this sentiment is to Jeff Knupp’s story of building Bull: Python and Flask are ridiculously powerful. Probably not coincidentally it is also a story of using Flask :)

9 thoughts on “Being amazed by software development

  1. Roger says:

    We go one step further and just put the generated doc in a Dropbox folder. That lets any dev update any doc, and has it all available locally for searches, offline use etc.

    Also your captcha is idiotic. If using words then allow enough space for words.

  2. Dmitry says:

    Rob, can you please be more specific on power of Linux compared with Windows? I did my own experiments, and Windows seems to be the only one dev OS for me, at least for 3d art, web and UI design.

  3. Dmitry says:

    And is it possible to get notifications on new answers? Now I read you blog with AOL Reader, open your article on the site to post comment and then keep tab open for several days refreshing it time to time to see updates =) I suggest to have “Receive email notifications” checkbox right after email text box.

  4. Dmitry says:

    And last thing in my mind – useabilty wise captcha math should be before Send comment button. E.g. on the left of it, not under and on the other side. Also button itself should be disabled if answer is not presented. And it would be nice to give a hint on the math and button combo. And you can use placeholder text instead of labels on the right ( ).

    So, one image to demonstrate the idea:

  5. Regarding the captcha, this is just a wordpress theme and plugins. I am not going to customize them or hunt around for a better theme right now. Sorry if it isn’t enjoyable! I appreciate you commenting and telling me about it, I’ll keep this in mind when I look for a new theme.

    I’ve installed a comment subscription plugin, you should now have the option.

    Dmitry, regarding Windows vs. Linux, I will try and make a longer post about it.

  6. Dmitry says:

    Rob, I’m subscribing right now!

  7. Shekhar says:

    Hi Rob,

    I struggled with same issue and had similar thoughts. But wonder what was broken when you used hasdocs? Is it correct to say that your use case was hosting generated html?


    1. Hi Shekhar. Yeah, my use case was a dynamic frontend for static HTML documentation. hasdocs wasn’t working at the time- is it working now?

  8. Shekhar says:

    No I haven’t tried it as it needs access to github repos including private ones and I can’t take chances with some of the repos. But may be I will create docs only account and will try out :)

Leave a Reply