Last Tuesday, June 7th 2022, I did a short talk at Tidelift's opensource celebration event Upstream. They had asked early May if I wanted to do a 10 minutes presentation based on this blog post: My first open source project.
Btw all the Upstream talks are available for free at Upstream.
Tidelift
It was actually my daughter Margot who works at Tidelift that came up with the idea to have me do a talk about my experience starting an opensource project.
After I accepted, had to sign a release waiver and got some useful instructions about the presentation. Since Covid this event is held online and all the talks are prerecorded and then submitted for an video edit round where some Upstream branding is added.
I had a deadline of May 13th for submitting the video. This was the first time doing a presentation in this way and his been quite a while since I had done a public presentation. When I still worked at Oracle we had internal presentations for a few people and normally with some slides and a spiffy demo I could wing it.
In the talk I wanted to share some slides but also incorporate a short Reken demo. Since switching between screens from the slides to a demo and back is always a bit messy came up with the idea of creating a slide show presentation with Reken and then incorporate the demo into the slide show. This may have been a bit of procrastination move, to not have to think about the presentation's content.
Fortunately I did not take me long to build the slide show presentator app and I actually made it available as a separate GitHub repo. I used the app to make an outline of the topics based on my "My first opensource project" blog post.
hbroekWith that in place I created a small little video recording setup. From the indoor cycling training class I still had a good microphone and for the video recording was initially thinking of using my gopro but got too complicated and just used the laptop's video camera. For the recording itself I used the Zoom conference software's recording feature. A tip from Tidelift.
At me first recording attempt I winged it. After I finished the recording was way too long with 20 minutes and the amount of "ehs" was baffling. I then tried it 2 more times but did not see a lot of improvement. The wing it approach did not work. I then wrote down the text based a video recording. With an IPad too the side showing the text I could now read and that went much better. With a few more attempts I had a 10 minute recroding without "ehs". I saw it was good, not great. The downside of reading is that sounds a little robotic, but it would have to do.
After converting the recording into mp4 submitted the recording to the Upstream team. Now it was waiting for the official Upstream event at June 7th.
The before I had already preregistered and activated my chat account. The presenters were asked to be available during their session to answer questions on the chat.
My session started at 3:45pm. Earlier in the day had attended some other talks to get a feel of the proceedings. I was ready behind my computer at 3:15pm when Margot texted me that she he previewed my video and that my head was cutoff in the video. That would have been a bummer. Fortunately Margot was able to upload a differently edited video where my head was not cutoff, just in time before the presentation began.
After a countdown my presentation started. Fortunately my head was fully visible. There were a number of questions and comments on the chat which I responded to. Apparently there were 20 unique viewers during the event. And after the event there were another 17 views and that will probably continue to increase. On a real conference that would be a small side room. Well you got to start somewhere.
Overall a great experience and with Reken becoming more and more mature, now is a good time to start to do some other activities such as marketing and community building.
p.s. here the text that went along the slides:
Slide 0
Hello everyone, welcome to my talk. Do you have an idea for an open source project but thought it would be too daunting or scary to start one? In this presentation I hope to address some of these thoughts. For experienced contributors this talk may be an amusing walk down memory lane.
Now if you notice my “slight” accent and wonder where it is from. It is definitely not a Bostonian accent, but my Dutch seeping thru. I moved from Holland to the United States 24 years ago. I guess I will have to live with it.
Slide 1
Today I’ll share my experience with my first Opensource project Reken that I started just over a year ago.
Slide 2
After a brief bio, I’ll give a glimpse of what Reken is about and then we’ll discuss my experience via the choices/decisions I had to make, the tasks that I have done so far and what code distributions Reken made available. Since I am only at the beginning of this journey, we’ll go through some of the todo’s that there still remaining. And last we’ll wrap it up with some takeaways.
Slide 3
My name is Henry van den Broek, I’m a software engineer. I have 30+ years of experience in software consulting, development and management. First in Europe and the last 2 decades in the US. The fields I worked in are Business Intelligence, Data Visualizations (think charts) and web development, which was mainly focused on frameworks.
Besides coding, my biggest hobby is cycling. I love long distance riding adventures and I race cyclocross.
And as of last year am the creator and developer of Reken.
Slide 4
Where did the idea for Reken come from? I have experience with a number of web frameworks and also used vanilla javascript to build applications. Both have their pros and cons, but I was looking for something in between. With Reken there is just one javascript file, it will look at a few additional DOM attributes and based on that builds a controller / calculating model in the background that keeps the UI up-to-date. Hence the name Reken, it is the Dutch word for Calculate. Reken is a quick download. minified and zipped it is 5kb and requires no additional tooling.
Slide 5
Now I’ll show you a quick demo. On this screen we see a an image and a slider. With the slider we will rotate the image. The image rotation is set with the degree value in the Reken data-style property and the degree value gets updated by the data-value attribute in the input range control…. Notice the demo also updates the degrees value in the code snippet :-) Other Reken features are looping, conditions, rest calls and more.
Slide 6
One of the first things I ran into when opensourcing Reken is all the choices / decisions you had to make, of which the consequences were not immediately clear.
a/ Opensource? When I started prototyping I had not been thinking about open sourcing at all but once I made progress I thought, wow this could be really something others may benefit from as well and when I demo’ed it to some folks, they encouraged me to open source it.
b/ With every software project you come to a point where you want to put it under version control, at that point decided to host the code on an online git repository. I researched some that where available GitHub, BitBucket and GitLab. Seemed that GitHub was most geared towards sharing code with the world.
c/ Then the question of license came up. During the GitHub project setup actually. Since my goal was to make the code accessible to everyone, the MIT license seemed the most appropriate.
d/ For version numbering I used the semver scheme, as I was used to it from other projects. Reken is currently at 0.4.2 and had 10 releases so far.
e/ In past projects, we collaborated using pull requests for code reviews etc. I initially started doing that too. But it turned to be just overhead. And for now I just push directly into main. Branches I have used occasionally, but also seem overhead at the moment.
Slide 7
Once I had submitted my initial push of my the code, I realized it would only be the beginning. As a user of opensource projects there all these expectations that go beyond just the runtime code. Tests, Demos, Doc etc.
a/ You need a test suite. Even though I already had a test suite, I actually forgot to include it in my first push :-) Oops.
b/ I am visual learner so for me demos are very important. From very early on I had a suite of demos and also a REPL to play with Reken.
c/ Documentation is not my favorite area. Although getting better at it. I used the Github’s builtin readme where you can write your documentation in markdown. Code documentation is probably the opposite of a super power for me.
d/ For the longest time I stayed away from Github Actions and Github pages. It was not clear how invoking these features would be affecting the repository and what kind of clutter it would create. At the moment I use actions to minimize and zip the javascript code, I also generate documentation for the Home page.
e/ In the end I did not use Github pages for the Reken home page, but host it on Digital Ocean with an automatic push when there is a repository update. Reken now has its own domain reken.dev and it hosts the code, live demos, REPL and documentation.
Slide 8
To distribute the code I use the standard Github clone feature, where one can download a zip, or do a git pull of the repo. I also made a download available on the reken.dev website. At some point I ran across a service called jsdelivr.net it makes public GitHub repo files available via links and it even serves versioned files. This allows folks to start using Reken by just adding a link to their web page, no download needed.
Slide 9
Here are new experiences I know I will need to have. So far the Reken repo has been crickets, the chance of organic discovery of that 1 repo in over 100 million repos is very small. So here some things I will need to spend some time on. Marketing, well this talk is part of that. A little out my comfort zone. Also will need to setup some kin of support channel for questions folks may have. Currently thinking of a discord channel. With that channel also hope to build community around Reken and on the longer term hope to collaborate with other contributors on Reken or related functionality.
Slide 10
Here some takeaways from a rookie opensource developer.
a/ Take your time to validate your code. After a year I finally feel there is a critical mass of functionality and stability. Besides writing tests I also validated by coding various use cases. With that I discovered a slew of bugs and gaps in functionality.
b/ Don’t let all these choices and decisions paralyze you. Make the call and if needed… revisit. Even your license you can be changed.
c/ As long as you are the only contributor, skip the overhead of branches and pull requests and just merge into main directly. Just make sure to review your pending changes locally before committing.
d/ After more than a year Reken is still pre-release. During that time I already had 2 major rewrites that affected API and behavior. And as long as I do not have any serious amount of takers probably keep it that way.
e/ Last takeaway. Give yourself time. Don’t worry about that first push, just make sure your code is in source control. You have plenty of time to hone and spruce it up. Not that there were hordes of developers trying to pull it out of my hands.
f/ Did I get myself another job? For now having the fun of writing something what I think is really powerful, cool code and sharing it with the world is worth it.
Slide 11
Thank you for taking the time to view my presentation I hope you were able to take at least 1 or 2 ideas from this talk :-). Also want to thank Upstream / Tidelift for the opportunity to present. And I want to thank all the Unsplash photographers for their beautiful photos.
Slide 12
Last but least. If you want to check out Reken. Here some links to get you started: The qrcode on the right brings you to this presentation. You can then access these links to the Reken repo, home page and my blog.
Oooh and by the way… These slides were made with Reken :-)
Thank you ……. :-)