HTML All The Things - Web Development, Web Design, Small Business

Documentation helps web developers navigate CSS frameworks, WordPress plugins, and helpful npm packages. Without it, we're left doing trial-and-error for hours, or left to community support from potentially dated forums. When documentation is bad, it can cost the documentation owner customers and trust from the community, but when it's good, it can save developers time and drive trust in the product. In this episode, Matt and Mike discussed the price of bad documentation and what makes documentation good from the perspective of a web developer.

Show Notes: https://www.htmlallthethings.com/podcasts/the-cost-of-bad-documentation-and-how-to-fix-it

Scrimba Discount: https://tinyurl.com/ScrimbaHATT

This week we discuss breaking out of our comfort zone to finally develop an app via a coding challenge.

• Parameters
  • Our idea needed to be something that was accessible, yet popular enough to get in front of people and actually get downloaded
  • In order to get downloads we knew the reach had to be decent, it had to be something that people would find useful, but it had to be simple enough in order to be developed quickly
  • We decided to analyze our previous experiences in launching apps, specifically our Chrome App and Chrome Extension collection
  • What we found was that, with very little promotion on our end, making a product that compliments an existing popular product gives you exposure through “osmosis”
  • Specifically speaking, our most popular app is Multiple Accounts for Outlook.com, which allows people to quickly switch between multiple outlook.com accounts and their associated web apps, like OneDrive
  • From there we took a look at our recent personal app experiences, as well as the Google Play store - our targeted app store
  • All of this ultimately boiled down to the next subsection “The Decision”
• The Decision
  • We’ve decided to do a minimalist reddit news app that strips away any distraction from actually reading the news
  • We’ll get more into what I mean by “minimalist” in the next segment, but generally we’ll take away a bunch of the default reddit features that people can get distracted by
  • We also have experience pulling information from reddit, via Mike’s joke generator that he used on his Introduction to Vue.js Guide (https://medium.com/html-all-the-things/introduction-to-my-vue-js-guide-ee9f4baad61)
  • This app is far from reinventing the wheel, but it gets us going on finally releasing an app on Google Play, which we’ve been talking about for years, but never done
  • The app will be monetized by ads, however, we plan on making the ads non-fullscreen and non-intrusive so that users aren’t bogged down by ads that have issues loading - this will be our first encounter with ads in an app as well so we’ll see how this strategy moves forward, maybe it’ll change, maybe it won’t work at all
  • This app is rather simple in design and scope, but it’s actually accomplishing a great deal of smaller points that we’ve been aiming to get done specifically...
• Accomplishments & Goals
  • Trying out a community event: One of our goals with HTML All The Things was to get the people involved to some extent if they wanted to try out new things for us. This coding challenge is the first of its kind for us, and we’ll be the guinea pigs to see if it works out - maybe if it goes well we’ll do a public version of some kind
  • Social media coverage - Right now we post about our podcast episode releases, share people’s work, etc. However, we’ve been wanting to try and “live post” to an extent. Share work as it’s being completed, so we’re aiming to share a bunch of content during this coding challenge’s time window. Things like posts of our progress as they happen, maybe get some videos in there - we’ll have to see how it pans out.
  • Releasing an App: We’ve been talking about releasing an app on Google Play for a long time and we’ve always brushed it off, this challenge should give us a push to actually get it done - even if we fail the challenge and don’t release the app on time, we’ll have dived into the app development so much that we’ll essentially have no choice but to release the app for fear of wasting all that time - forcing ourselves to take on the risk
  • Furthering Our Knowledge: We’re planning on using pwa for this project, however, we’ll be needing some plugins and functionality that we’ve never used with it, so we’ll be learning on the fly

• If we assume that our “decision” in Segment 1 is final, and we are actually doing an Reddit News App, let’s dive into how we would take this project on
• One of the most important things we need for this challenge is to identify what our MVP (Minimum Viable Product)
• Research, Design, Development, Deploy
• Research is complete already, app decision has been made
• Mission Statement: Simple Reddit new aggregate for people that want to quickly view the news in their area without any distractions.
• Parameters of the challenge?
  • What can we do before/after?
  • What we need to accomplish during the challenge?
  • What’s the endgame?
• Design
  • Use a css framework?
  • Light/Dark theme?
  • Simplistic no bs design to to make the news a quick scroll away
  • Naming
  • Features
    • Pull posts from multiple subreddits and display as one multi subreddit
    • Remove all unneces...

Note: We had some audio issues with the first upload of this episode, if you hear nothing, simply delete your version and re-download to get the updated file. Apologies for the inconvenience.

• As apart of this challenge we were allowed to plan, design, and research before the challenge began
• To prepare we did some research on PWAs and their functionality
• We also researched other news apps, and what subreddits would be the most useful
• From a UX perspective, we took a look at which features a Reddit user would need and expect from a Reddit app - minus the social features of course
• From this we came up with some wireframes to guide our design throughout the process, which we modified on the spot to accomodate for a “open Reddit post” button alongside alternative share options for PC users
• We also had a discussion regarding the addition of custom news sets, where users could select a bunch of subreddits to pull into a single custom feed - this ended up using up a decent amount of time and we didn’t put it into the app in its current state
• One other design challenge that we had was making the design pop
• Since this sort of app is so text-heavy we were concerned that its monotone nature would end up making it boring, or otherwise, look unfinished and rushed. However, after spending more time on Reddit we realized that this type of app is more utilitarian than it is flashy, so we decided to place it in a dark theme and let the links “do the talking”

• Development went smoothly for the most part
• We were able to complete almost all the features that we originally set out to make, including a few extra ones
• We had a few bugs popup that were dealt with quickly, namely some responsivity issues with overlapping and some time stamps that were coming in as negative numbers
• Vuejs seemed to almost accelerate development due too it’s built in development server and its short code nature for functions and listeners
• Vuejs also created the template for the PWA functionality through the Vue CLI
• App functionality implementation went as planned and didn’t pose much difficulty other then a couple of hiccups and glitches that had to be fixed
  • Showing how much time has elapsed since each post was posted showed to be kind of annoying because of how reddit handles UTC time. I have to multiple the time by 1000 to match with the the current UTC time
• Working with the reddit api is awesome and a great way to learn API’s and working with json
• The app is pretty much feature complete as in line with our MVP (minimum viable product)
• Couple of features we are looking to add would be :
  • a way to create a custom news group
  • Light theme to go along with the current dark one
• The motto for adding features to this is “Is that bullshit?” if we think it is, then we don’t add it

• So we’ve already had a few episodes where we talk about deployment in a little more detail but it’s valuable to mention how we went about doing this for the 24 hour challenge aspect
• This was by far the most frustrating part of the entire day as this would be only my second time deploying with Docker and to digital ocean
• It is simpler than the html all the things deployment because there is no server side containers but due to the time constraint and the fact we started deployment only at around 12am it turned into a problem
• The initial deployment as a web app went ok until we hit the SSL certification
• We used the same method as with HTML all the things, where we are trying to certify a docker container running nginx using certbot on our ubuntu digitalocean droplet
• Unfortunately I didn’t have a lot of experience and combined with already being mentally exhausted I went into a try everything approach instead of using logic
• Logically looking at it with a fresh head after getting some sleep got a solution in a matter of minutes
  • Although this was frustrating this is all part of these short time challenges and must be overcome if anyone wants to be able to work in crunch periods
  • Sometimes it’s important to step away, as I did that at least 2 or 3 times during the challenge to solve random issues
• For next time I think we might do a initial pre deployment before the challenge to at least get the ssl and nginx container worked out, so we have more time to focus on actually developing

• Disclaimer: We have minimal experience with PWAs in both the development and consumer side of things, so these are simply our opinion...

In this episode we take a look at taking on complex tasks in a field where you're not very experienced, something all programmers must do at one point or another in their career.

• This segment is going to focus on our experience configuring a vuejs service worker - I went in with no previous hand-on experience, a complete newcomer to service workers and an amateur at vuejs. Therefore this process is no doubt clunky, but as you’ll hear that’s exactly the point
• I want to be clear before I dive in here that we’re using the following particular scenario because it was recent, we are not pointing the finger at any of the plugins, apps, or resources that we mention below. The issues we’re discussing are industry-wide, and not on a specific service, platform, or individual.
• Recently we went to work with service workers on a Vue.js app (No BS News for Reddit)
• As apart of the coding challenge we had already had a basic service worker setup that allowed the local assets to load when the app was offline
• This functionality was made using a pwa plugin for vuejs
  • We left this plugin mostly, if not completely, in its default configuration
  • This default configuration registers a service worker and then generates a service worker file which caches those offline assets
  • Mike got the project to this point during the coding challenge and then I took over
• This is where things all fell apart for me:
  • I had done a couple of days on reading basic service worker configurations and functionality and then finally decided to dive into our project
  • First thing I did was look around the file structure and I find a file named registerServiceWorker.js
  • This file contained an import line regarding register-service-worker (which fueled my initial Google searches) as well as the registration and basic responses that you’d expect such as successfully registered, detecting offline, etc.
  • Searching register-service-worker led me to the page that I linked above, which had some very brief documentation and a code example that looked like our registerServiceWorker.js file (so far so good)
  • From there I ran some tests in Chrome, checking for service worker install, checking offline mode, etc to get my bearings
  • At that point I wanted to start adding some code of my own to the service worker, from my readings I knew that the service worker was definitely a separate file and from the registerServiceWorker.js file I could see that it was referring to a file called service-worker.js
  • Searching the directory for said file revealed that it didn’t exist
  • I then went and checked in the browser again, taking a look at the sources tab to find out what file was running the service worker, it showed that it was definitely service-worker.js - which indicated that the file was being created dynamically as apart of the build process
  • This led us down a rabbit hole of finding how to inject my service worker code into this autogenerated file
  • Overall, we eventually did find a solution for the code injection, however, it was not in the original register-service-worker documentation, nor was it discussed a lot on stack overflow
  • We did find one Stack Overflow thread that did help, which led us to a useful blog and a couple of interesting links - I also found a separate page on npmjs.com somewhere along the lines which contained the missing code we were looking for
  • Basically we needed to add some injection configuration into the vue.config.js file and then from there make our service worker script
• Now I know that’s long winded, but it points out some very important problems/concerns:
  • The newcomer effect is alive and well, I wrote an article on Medium about what I call the newcomer effect a long time ago, it basically means that any documents/signs/directions that are available for any given experience rarely take into account the needs of those that are complete beginners - increasing the entry “budget” for newbies
  • I’m not sure how documentation writers do it - maybe it’s because they’ve been working on their projects for so long - that they completely miss major steps in their documentation. It’s got to be mentioned that we desperately need better documentation for beginners and furthermore, more linking between potentially helpful guides
  • In this particular case, maybe it’s because many folks won’t write their own service worker, but rather just want the default to cache the local assets and that’s it, but shouldn’t it at least be mentioned that if you want to write your own service worker - please see x
  • Toxicity and useless comments are alive and well - on various forum posts, comments, and of course Stack Overflow posts there are typically an abundance of comments that dismiss questions...

In this episode Matt and Mike sit down with Alexandria to discuss her journey through the tech world. The trio discuss things like different paths to get into tech, how tech differs (advantages and disadvantages) for women in tech, and also talk about being a person of colour in tech. If you're interested in unique career paths, workplace diversity, and some straight up tech talk - you're not going to want to miss this episode!
Thanks to this episode's sponsors CodeCast and Showwcase (Invite Code: JoinHATT)

Show Notes

Alexandria's Twitter @AlexandriasTech
Alexandria's Youtube
Alexandria's Twitch

You can find us on...

Facebook | Twitter | Instagram

RSS | Patreon | Spotify

Medium | YouTube | GitHub