A (MUCH BETTER) Letter From Front End
Several weeks ago, Web Frontend became a proper team within HackRU's RND. 🎊 Inheriting the codebase from a very important previous developer, our team set out to accomplish the following tasks:
- Gain a thorough understanding of the code and the technologies used for the front-end at its operating state
- Incorporate Redux - this allowed us to manage state, logic, and component rendering separately
- Get rid of using MLH Logins, since there was no apparent secure way to transfer MLH tokens to users after login using LCS
- Fix any issues that would be raised during the development process
- Document the code and its reverse-engineered architecture (when no pre-existing documentation was provided)
- Start using Travis CI and building tests using Jest and Enzyme
Throughout the front-end dev process, we ran into some complications with regards to design and front-end visuals. Here's where things went wrong:
- We assumed MND was properly equipped to provide the documentation/content we required to make the front-end successful
- We did not make a full attempt to understand the MND situation so that we could make the MND-RND interaction more seamless.
- With failing above, we did not alert the executives for help/leniency on deadlines, and shipped the result as is.
.
We aim to pass on the torch of establishing a better design and structure to the Spring 2019 team, something along the lines of [this plan]. With the support of a more manageable code base, continuous integration with testing, and accessible documentation, the expectations for next semester will be higher.
I hope that this letter can provide some perspective for the next Project Lead and anyone else who wants to work on a front-end for LCS. For now, we appreciate your feedback. Every week we work on issues, most of them cosmetic. Feel free to open new issues if you have any constructive feedback. (something other than "this website is 💩" please!)
So why didn't we start from the design perspective?
Let us first rewind to late December/early January 2018. At the time, the people working on RND were in a very difficult spot. Many of the teams were short on available coders, leaving less manpower for ongoing projects. The RND team was also busied with a separate event, which came with its own issues and deadlines. (The upside was that the event became a valued test battle-ground for many of RND's projects.)
The relevant result: much of the React ended up being written in a rush by people who hadn't accumulated enough familiarity with React or JavaScript to do so cleanly. The same can also be said for the website HTML and CSS. However, once it was put together, everything still worked smoothly, so to speak - several days after the deadline.
Had there been more people available for a dedicated front-end team then, at this point there would have been a post-mortem redesign and immediate refactoring effort. But there were not enough people to do this, so this effort did not happen.
Let us fast forward to immediately after HackRU Spring 2018 in April. At this stage, the front-end was functional and pretty responsive. It was also theme-consistent, which was nice. But behind this part of the website was a literal code monster, which you can view here. This file, which according to Github, has over 1000 lines, was the result of many injections and code folds. However, this file was just an example of many examples of problematic or otherwise sloppy code.
Absolutely not. This problem occurs even in single-developer side projects. When deadlines strike and resources are choked, the decision falls between hacking together a deliverable or not delivering at all. In an actual company we'd be tackling this at a higher level by negotiating better deadlines and implementing a scheme such as PR2 or TDD. In my limited view, to expect such out of an undergraduate-level team of volunteers seems like a mismanagement of expectations.
After researching and discussing many of the existing issues with the previous code writers, we identified the problems:
- Unorganized code
- No evident design documentation (we found a style guide later)
- An inadequate understanding of React
- MLH Logins (a whole separate issue)
- Lack of style discipline
In other words, we were in technical debt - in exchange for a quick and functional deliverable for a looming deadline, a large load of brain-work was deferred to those who would take over at a later time.
Fast forward to the last week of June 2018. With the August 4/August 5 live-date, I had 5.5 weeks to work with. The team would be on-boarded in a week, so that left them 4.5 weeks. We put together a laundry list of things that we absolutely, absolutely, had to do, and another list of things that we absolutely had to do, but later.
In my decisions, I took a gamble to completely replicate the behavior of the first iteration from Spring 2018 instead of redesigning from scratch.
This cut out plenty of menial tasks like grunt-writing CSS or HTML/JSX and forcing MND to make a brand new mock-up in a week, and focused the team's efforts on the JS. By around the 3rd week, MND + RND provided the new design CSS, which was OK'd and integrated in. The result of their work is what's currently visible on the front-end.
- Understand just what was going on and what each component's responsibilities were
- Refactor the code to incorporate Redux so that the components and the state could be worked on separately, having components affect the state directly or handle logic was difficult to manage.
- Get rid of using MLH Logins, since there was no apparent secure way to transfer MLH tokens to users after login
- Fix any issues that would be raised during the development process
- Fully document our code and the reverse-engineered design (no design documentation had been previously provided)
- Incorporate requested features
- Set up Travis CI and structured testing using Jest and Enzyme
- Continue to refactor remaining code
A large mistake we made in this iteration was making assumptions about MND operations - that they would handle certain things like creating wireframes, mocking up a new design, getting user feedback, putting forth the new design, and handling CSS tweaking throughout the process. What really happened was just a submission of a new design, which was OK'd by the relevant authorities. This was fine for our purposes, but provided no framework to make improvements. User feedback also did not tend to agree with the provided design.
A second mistake here was probably that we did not raise hell at all on the above. With the amount of time left before the launch date, we operated under the assumption that "our hands were tied" on this design, and there would be no time to argue for a re-work, especially with all the other tasks to care of. We ran into friction debt: In exchange for avoiding a difficult conflict in the moment, we made our work more difficult, which would increase friction later. The despicable result of this is that our team is perceived as "responsible" for a design that people don't like, when it is not our responsibility. In reality, an alternative strategy existed if we wanted to uphold proper practice: to hold the deploy date hostage until a design and documentation could be agreed upon. (But of course, that would lead us to be perceived as uncooperative, wouldn't it? 🤔 )
Finally, MND refused to touch our repository. This led to the following pattern:
This is not the point of having independent teams. If someone has the knowledge to fix a problem, there is nothing preventing them from implementing the fix. If MND is to design, then they must take ownership of the process and make the thematic/cosmetic choices they need to, without the impression that there are crutches in place. From a wider perspective, it was imperative for MND and Front-End to have been on the same page from the beginning - but the previous implementation of this was basically leaving all of the visual work to one person.
After having a meeting with the MND director, we found that the responsibilities left to MND were above most of their experience level - in the transition, they were not made
For this reason, Front-End is looking to expand the team to include an exclusive designer. This designer will be in charge of working on the website design aspects (including wireframes, visual mock-up, and UX component design) and implementing them via HTML/CSS/minimal amount of JS. The designer will be Front-End exclusive so that they could work in tandem with the development team and their deadline, thus removing ambiguity and inter-organizational delay. MND's input on the matter may be limited to thematic selections, such as colors. More of this is detailed in the [future plan] for Front-End.
The source code needs to be refactored (again!...slightly), but this time for the purpose of better practice, such as the isolation of responsibilities or avoiding non-deterministic behavior. This also makes the code much easier to test - when multiple responsibilities are attributed to one function, the number of different tests that need to be written for that function increases exponentially. We also want the Flux pattern to be properly implemented - containers should handle connections to the redux store, and components should simply render the necessary JSX.
It is also a good idea to start working on features that could be activated in anticipation for organizations that may need them. For instance, perhaps one day a volunteer or mentor sign up form may be desired in the website. Maybe it would have to be written in React, as it would rely on the info provided in the regular attendee application. Or maybe not - this depends on what the specific needs will be.
From an attitude perspective, I think Front-End can manage to be a bit more assertive in its decisions in comparison to other organizations within HackRU. Our deadline hits harder and faster than any of the other teams in RND, and perhaps in the entirety of HackRU. We should not have taken the resulting design decisions lying down. We should not have agreed to a website walkthrough with only three days left to deploy date. We should have insisted on having AWS Console credentials earlier. We should have insisted on having a separate test instance of LCS to the extent of putting up our own.
In any situation, having more organized information up front greatly increases chances of success. Having a better picture of what is required to succeed allows us to fight for what's needed way before it's needed. I apologize to my team for putting us in poorer positions because I did not have this down.
If you think the problems discussed above are rare occurrences or symptoms of some disease of inexperience or lesser skill, think again. These kinds of situations with "we can only do what we can do" strategies happen all the time - simply ask any experienced professional.
Here's to never seeing this again:
