Attempting to create websites that other people can maintain
In winter of 2017, I was part of an ENG 100D Global Ties project to create a website for the students of an applied biology class in Oceanside. Our team learned a lot about the human-centered design process, including how to do needfinding, get feedback, and present our project. We had to wireframe the website, incorporating ideas and input from the middle school students, and write the code itself for the website.
While the website itself turned out looking nice, one issue we had was how our client would maintain the website after we finished the class. Our solution should be sustainable, as that is one of the goals of Global Ties projects. At the start, we hoped that the students could maintain the website, but we realized that the responsibility and knowledge needed would be too much for any of the students, especially since the class wasn’t a technology class. We decided that we should have the teacher be responsible for updating the website.
At the end of the quarter, we visited the middle school to hand off the website to the teacher. We tried setting the tools on his computer the way we had in development but found that the school laptops had restrictions on what could be installed. Furthermore, we realized that the process of what he would need to do to update the website could be complicated even for him. He would have to edit the HTML pages and commit the changes to GitHub. We visited him one last time at the beginning of the next quarter to do the best we could to transfer over the files and let the team working with him during spring quarter continue the project. During this visit, we also found out he planned to go teach in Bali for a period of time starting next year.
As time went on and I did other projects, I saw how hard it was to hand off a project to other developers. Handing off a codebase to someone with minimal technical experience requires even more care.
The next school year, I joined the board of UCSD’s Society of Women Engineers and we had a new website that was commissioned over the summer since the old one was lost during the period of time when the club wasn’t properly registered with the university. However, this new site wasn’t on our domain because the person who made the site didn’t know how to make that part work. At the time, it was hosted on Siteleaf, a content management system, and we were given access to the Siteleaf account where we could make updates to the site. Due to confusion about how to host a website on school server, SWE’s actual website was a temporary one that just had links to our contact information and social media accounts. How did the website get updated with this temporary one? Somehow, this remained a mystery.
In March, I was asked to help figure out how to get the website working. One of SWE’s former webmasters was working on it but couldn’t get it to work from downloading the files from Siteleaf and putting it on the server. From the Siteleaf account, I could see the linked GitHub repo. I did a Google search on it and found the repo. Confusingly, the repo looked empty. As it turned out, all the code was on a gh-pages branch. There was very little documentation, only a README that said
Slightly opinionated, personal boilerplate for small to medium sized web projects. Based on Jekyll and Grunt.
It was only there because it came from the README of the boilerplate the creator made. This gave me a direction to go in at least. I looked into Jekyll and set it up on my computer. Since Jekyll is a static site generator, it’s the files in the _site folder generated by Jekyll that you need to have on the server. Otherwise, you’ll see the actual Jekyll syntax on the webpages.
To get the files on swe.ucsd.edu, I needed to scp the files to the swe.ucsd.edu server. I heard some things from the past webmasters about how to update the website, but it wasn’t entirely clear to me how to access it. I had to make some inferences from that information and from UCSD’s page on how to publish personal webpages to figure out how to ssh/scp to the swe.ucsd.edu server.
Once I put the contents of the _site folder into the public_html folder on swe.ucsd.edu, it worked. For months, all the pieces were there for the website to work, but no one completely understood the system.
As the school year came to the end, SWE board members were encouraged to pass off important information to the people who would be taking over their role in what our president called a “knowledge transfer”. I had been working on a secretary onboarding guide since January, and I finally had to document the steps to update the SWE website. My audience was an electrical engineer and two chemical engineers, two with Macbooks and one with a Windows computer. My aim was to provide a step-by-step guide with exact command line instructions some explanations of each command. It went surprisingly smoothly. I also put in the repo’s README. Anyone who knows a little about the command line should be able to get the site up and running (but only able to actually change the website with proper credentials). If you want to have your own website set up in a similar way, the instructions are easily adaptable.
As a side note, another part of the knowledge transfer involved a script I wrote to keep track of SWE’s collegiate membership points. I initially wrote the script in Python and required downloading all the spreadsheets from the Google sign-in forms as CSV files. I later rewrote it as a Google Apps Script and had it so the spreadsheet could be simply kept in a folder in the Google Drive. It’s not a perfect as I wanted, only showing emails instead of people’s name and having manual adjustments being a bit clumsy. It seems to be usable, though.
The step-by-step guide was slightly tricky due to the fact that the website maintainer needed to install Jekyll and Ruby on their computer. This was necessary due UCSD’s restriction on users installing programs. I created a ticket with the IT help desk but didn’t get an answer before I had to pass off the website to next year’s board. As it turned out, IT responded some time during the last days of the school year to the SWE email which I didn’t see. In the fall, I got an email asking if I received the response they sent with instructions on how to get Jekyll working. I asked for another copy of the instructions, but was away at the time and had no access to a computer. They sent instructions, but I kept on putting off doing anything about it since I wasn’t even a student anymore. That is, until February 2019 when I got an email asking if the ticket was resolved yet. I finally followed the instructions, which were a workaround to install Jekyll in the user space, and sent new instructions to the current board.
If you know someone else is going to have to maintain the website later, prepare for that from the beginning. It could affect the design choices you make.
With the garden website, we thought of adding an admin panel to maintain the website relatively late in the process. It might have served us better if we used a content management system in the interest of sustainability.
If you are currently responsible for maintaining a website but know that you will pass on that responsibility in the future, document what you do.
The information about how to update the SWE website wasn’t passed on adequately. Looking back, I think everyone who knew how to update the website didn’t realize that nobody else knew how to update the website. This made asking questions difficult because nobody understood what we needed to know.
In a software engineering class I took, we worked on our project as if next year’s class would inherit it. Not every group’s project was actually given to the next class, but there were several years where the starting projects came from last year’s codebases. Therefore, documentation was important, and ambiguity would inevitably lead to future students cursing your confusing choices.
If you create a website for someone but have trouble getting it integrated into their system, document what you did.
The studio that coded the SWE website couldn’t figure out how to get it working on swe.ucsd.edu, so that was left for us to figure out. They left some ideas for possible problems that we could bring to UCSD’s IT help desk, but ultimately those weren’t the problems. It seemed like they didn’t know that we were supposed to ssh into swe.ucsd.edu to put our website files in a certain folder. Even though we were left to solve this technical problem, we weren’t given any technical documentation. We were only given the Siteleaf account, which would be fine if the site was working and our only problem was that we needed to update the contents of the site. It would have easier to resolve the issue if we had an explanation of how the code, Jekyll, Siteleaf worked. If any documentation existed, I did not have access to it at least.