Reflective Account
Background
The SHU Development Process [1] (shu-dev) is a soware development process and website that can
be followed by students at all levels as they work on both individual and group assessments. It is
based on the generic process framework described by Pressman and Maxim [2], and comprises ve
methodological stages: iniaon, planning, modelling, construcon and deployment. These main
stages encompass a set of support steps: analysis and design related to modelling; code and test
related to construcon; and delivery, support and feedback for deployment.
The current SHU Development Process, shown using an exploded view of the modelling stage [1].
The project has the pedagogical aims of creang “A bespoke development process can provide a
framework for students to follow, helping them in choosing appropriated approaches and tools for
their projects and beer engage with group members remotely. This process will also benet tutors
by providing a generic structure that can be tailored to each level of study and modules. We have
designed a soware development process that can be “instanated” into each level of study. The
process has been completely detailed by SHU students and provides a series of guidelines and
suggesons of best pracces”. It’s run by the Applied Soware Engineering Research Group (ASERG)
within the university’s Department of Compung.
Before I joined the project in early 2022, the process was documented through a series of Markdown
formaed text les [3] and made available through a hosted git code repository [4]. Navigang these
documents was clumsy and confusing, as it relied on the Codeberg repository interface to move
between pages. As the project is student-led, I quickly established that the content should instead be
presented through a dedicated website so that it can be styled in a format that is easier to read, kept
as an online resource for high availability, and made available to many devices through responsive
styling. This was especially important due to COVID-19 restricons in-place at the me and
connues to be a benet for teams that work remotely now.
MkDocs [5] was inially selected as it met our needs exactly; to turn markdown les into HTML
webpages. Styling the built-in ‘ReadTheDocs’ theme to match SHU branding was simple, however
customizing the site further, to support inline diagrams, was cumbersome due to the Jinja templang
engine [6] that was used to build HTML pages. MkDocs proved useful as we could produce a ‘good-
enough’ result quickly, but I knew as I was developing it that a technology change would be
necessary.
Aer collang and analysing feedback on the MkDocs site for the 2021-22 academic year, it was clear
that the site was helpful, however students felt they had to navigate through too many links to
access the content they wanted. This was in part due to the level-based and process-based division
of content, which lead to content duplicaon in some places.
The soluon for these issues is the Astro framework [7]. It has nave support for Markdown, so
minimal content changes were needed to migrate and the largest advantage is the ability to mix
components from other frameworks like React, Vue, Svelte, Tailwind, and more into stac HTML. This
is ideal for a site like shu-dev because content updates are infrequent. Custom funconality is also
easier to implement through Rehype [8] and Remark [9]. I wrote plugins and components that will
return plaintext (for search result indexing), add client-side search funconality, and lter content
based on a visitors chosen level of study. I’m concerned that these customizaons may be dicult to
maintain within the project once I leave at the end of the year, however their modular nature means
that it is possible to remove this funconality enrely, or for it to be updated independently of the
rest of the site as an npm package in the future. The current version of the site went live in January
2023, with the old version maintained for posterity on a legacy address [10].
During the academic year 2022-23, the process has been used by some module leaders as inspiraon
for the delivery of their respecve modules. This includes being detailed in the marking scheme for
the level 5 Professional Soware Projects module. The scope of the project is being expanded across
all Soware Engineering modules for the academic year 2023-24, so I’m pleased that the project is
having a posive and lasng impact on my course.
Requirements Engineering
The aims of the project mean that both the gathering of requirements and the measurement of
outcomes is best done through qualitave means; most aconable requirements and feedback have
been collected via open comments from sta and students.
From Sta
The process for validang content thus far has been to map each topic or secon to the sta
responsible for teaching it at each level of study, then ask for their approval and amendments on that
as well as the rest of the site. Sta have not informed the layout or design of the website and aer
the inial deployment, there have been no suggested content changes. Content has been added and
amended by the shu-dev team based on previously agreed lists, or my own use of the site.
From Students
Students have told us what they expect from the site via the annual survey and in-person comments
recorded by the team. Themac analysis has been used on the survey to group feedback and turn it
into priorized, aconable tasks stored as issues on the Codeberg repository. We’ve previously
received comments about physical and cognive accessibility, example consistency, and broken links.
Preferred Pracces
The current pracses work well and allow the team to work around other obligaons, such as
teaching and assignments. Addionally, the overall project requirements have remained consistent
across academic years. Coupled with module content being approved before teaching commences,
there is lile need to increase the frequency of major updates beyond once per year. With that said,
the site is designed to be used all-year, every year, so I feel it would benet from integrang passive
feedback collecon. This could use a rangs paern, modals, or inline hints [11]. The benet of this is
that feedback can submied as-and-when it is noced by users and removing the need for a
separate account & interface, as is required with Codeberg issues, would make giving feedback
easier. My hope is that feedback collected this way would not be reacted upon to in real-me but
folded into the exisng site update workows. Consideraon would need to be given to the structure
of the form so that it’s as useful as possible. For this reason, I think Socrac Quesoning [12] should
be used. This would make connually elicing requirements and ensuring content is up to date much
easier. A suggested list of quesons could be:
• Feedback Locaon:
o This page
o Another page
o Whole site
• Feedback Category:
o Content
▪ Jargon
▪ Missing
▪ Typo
▪ Other
o Website
▪ Bug
▪ Accessibility
▪ Feature request
▪ Other
• What is your feedback?
• What would be an alternave? (viewpoints and perspecves)
• Why have you given this feedback? (claricaon)
It’s worth nong, such a form would require honeypot elds or CAPTCHAs [13] to avoid malicious
submissions.
Design and Development Techniques
The design of the site has been informed by similar sites like ReadTheDocs [14], microservices.io
[15], and OpenAPI [16]. They use lists and accordian menus [11] that the development team decided
students would be familiar with from across the web, parcularly with code documentaon sites
they’ll also see elsewhere during their studies.
While implemenng HTML changes, I made sure to validate them against WCAG2.1 [17] accessibility
standards so that the site can be used by as many dierently abled students as possible. Axe
Devtools [18] was used extensively the Astro rebuild to do this.
As the content of the process was created before I joined the team, I quickly decided that I’d
“dogfood” [19] the process when it came to git workows and task management. This means
I use feature branches when I’m updang content and Kanban as a way of priorizing tasks.
I’m comfortable with the current design and development strategies. No changes should be made to
these pracses.
Test and Deployment Strategy
Current Tesng Strategy
Physical accessibility is tested using Axe Devtools to check for WCAG2.1 compliance, with issues
being xed during development or added to the Codeberg issues for the team to invesgate. Broken
links are checked using deadlinkchecker [20] and drlinkcheck [21]. As I’ve been the only person
developing the site, I didn’t move past manual unit and integration testing during the Astro
rebuild, as migrating content took priority. User Acceptance in the form of feedback surveys
helps the team test the site for system usability and user experience goals.
Current Deployment Strategy
The site is developed locally on feature branches [22], pushed to a ‘development’ branch where it is
then tested online, then pushed to ‘main’ before it is deployed live to students. Scripts are used to
ensure the branch repository structure matches that expected by the Codeberg host. This approach
ensures changes can be tracked and reverted if necessary - the site is maintainable.
Preferred Pracces
My ad-hoc approach to tesng has been the wrong one to take as it’s too easy to think “well, it works
on my machine”. Fortunately, bringing on another student, Will, to help with development means
they can focus on implemenng automated unit and integraon tesng via Playwright [23]. This has
already been used to nd an issue with the content lter controls on some pages. Further
development will see tests implemented to automacally nd accessibility issues and broken links.
I’m sased with the choice of Playwright for this purpose as it is based on the same Node.js
technology as Astro, so JavaScript can be used throughout the project. It also has a GUI mode so the
team can visually trace the results of tests to nd out exactly why they may fail. Finally, tests can be
triggered from the exisng build script for a full integraon and deployment process, or it will fail if
there are issues.
Evaluaon on Cloud Adopon
Content Hosng
The current site is hosted on Codeberg Pages [24], which is a free service operated by our chosen
remote repository provider. The serverless architecture ts our needs well most of the me as the
website build output is stac, however there have been intermient periods where the site returns
HTTP 500 errors, indicang a lack of resilience with the host. To migate against this, a content
delivery network should be used to cache pages and improve availability. Assuming this could not be
done via exisng SHU IT services, a small budget would be required for a domain and CDN services.
Given the low trac required by the site, enterpise-grade services like AWS CloudFront and Amplify
[aws.amazon.com] are unnecessary due to the amount of work required to set them up. A provider
like Cloudare could be a viable alternave host through their Pages product [25]. I see this issue as a
top priority, given that the site is being adopted across the enre Soware Engineering group.
DevOps & CI/CD
Our current integraon and deployment process has been streamlined using shell scripts. They’re
eecve for deploying code with minimal eort, however they are not connuous because they
must be manually triggered by a member of the shu-dev team. This is a shortcoming of the Codeberg
repository host, as it does not include automated CI/CD features. These are currently marked as
experimental in the upstream Gitea dependency [26].
My preferred pracse would be to move to a repository host that supports automated acons, such
as GitHub. This isn’t an opon as the ASERG team is hosted on Codeberg, so it’s prudent to stay with
the same provider for the sake of easier access management.
Content Management
Currently, content is created and maintained in Markdown les stored on the project repository. As
the development team is small and input from academics has not been as direct as eding les, this
is sucient. Also, given we work in the compung department, there is a low barrier to entry in
asking sta to raise a git issue or a pull request on the repository. With that said, the git issues have
not been used by outside pares and I can foresee a need to broaden and formalize the content
update process for the site to be maintainable long-term. For this, there are two new routes worth
assessing alongside the use of regular git features:
A content management system (CMS) would allow sta to add, update, and remove content through
a user interface and have those changes reected on the site. As useful as this is, it would introduce
operaonal complexity through the need for a backend to host content, and a review process to
ensure it is high quality and relevant. This means cloud-backed opons like Storyblock [27],
Contenul [28], Sanity [28], or AWS cannot be used. Instea, git-based tools like Tina CMS [30] or
Frontmaer CMS [31] should be invesgated, in order to reduce the eding complexity.
As outlined in ‘Requirements Engineering’ above, an inline feedback widget is an alternave to this,
as content changes can be submied by anyone via Plausible Events [32] and reviewed by the shu-
dev team before being implemented.
An instance of Plausible [33] is being used to anonymously track which pages are being visited,
though I don’t feel enough is being done to ulize this tool. To comply with GDPR regulaons,
analycs should remain as anonymous as possible, however I feel the team could invesgate how to
update the website’s tools and privacy policies to collect more useful informaon, such as which
study-level lters are being used, which terms are being searched for, or to add an opt-in feature for
the inline feedback widget.
Further Suggested Changes
Conversaonal User Interface
The site can be searched using keywords and fuzzy matching [34], which returns lists of related page
secons. It’s very eecve and I’m glad the soluon doesn’t rely on a third-party to crawl the site.
However, I’ve seen a rise in use of digital assistants like Apple’s Siri, or chatbots like Bard and
ChatGPT [35], mean that students may become accustomed to querying content using natural
language and expect the same in return. For this reason, future development of the site should
consider technology like Tensorow.Js [36] or the ONNX Web Runme [37] to implement a
lightweight, queson-answering, conversaonal interface (chatbot). It could be implemented within
the search funconality, or a standalone widget and it should target only shu-dev content to
maintain performance, safety, and relevance.
References
1. ASERG. (2023, April 10). SHU Development Process. Retrieved from
hps://aserg.codeberg.page/shu-dev-process/en/introducon
2. Pressman, R. S., & Maxim, B. R. (2010). Soware engineering: A praconer's approach (7th
ed.). McGraw-Hill Higher Educaon.
3. Daring Fireball. (n.d.). Markdown. Retrieved April 10, 2023, from
hps://daringreball.net/projects/markdown/
4. ASERG. (n.d.). Shu-dev-process repository. Retrieved April 10, 2023, from
hps://codeberg.org/aserg/shu-dev-process
5. MkDocs. (n.d.). Documentaon. Retrieved April 10, 2023, from hps://www.mkdocs.org/
6. Pallets. (n.d.). Jinja Documentaon. Retrieved April 10, 2023, from
hps://jinja.palletsprojects.com/en/3.1.x/
7. Astro. (n.d.). Astro Web Framework. Retrieved April 10, 2023, from hps://astro.build/
8. Rehype. (n.d.). Repository. Retrieved April 10, 2023, from
hps://github.com/rehypejs/rehype
9. Remark. (n.d.). Markdown processor. Retrieved April 10, 2023, from hps://remark.js.org/
10. ASERG. (n.d.). SHU Development Process (Legacy version). Retrieved April 10, 2023, from
hps://aserg.codeberg.page/shu-dev-process-legacy/
11. UI Paerns. (n.d.). Retrieved April 21, 2023, from hps://ui-paerns.com/paerns/
12. ASERG. (n.d.). Socrac Quesoning. Retrieved April 21, 2023, from
hps://aserg.codeberg.page/shu-dev-process/en/iniaon/#six-types-of-socrac-quesons
13. Cloudare. (n.d.). How CAPTCHAs Work. Retrieved April 21, 2023, from
hps://www.cloudare.com/en-gb/learning/bots/how-captchas-work/
14. ReadTheDocs. (n.d.). Retrieved April 21, 2023, from hps://readthedocs.org/
15. Microservices.io. (n.d.). Retrieved April 21, 2023, from hps://microservices.io/
16. OpenAPI Iniave. (2020). OpenAPI Specicaon, Version 3.1.0. Retrieved April 21, 2023,
from hps://spec.openapis.org/oas/v3.1.0
17. W3C. (2018). WCAG Content Accessibility Guidelines (WCAG) 2.1. Retrieved April 21, 2023,
from hps://www.w3.org/TR/WCAG21/
18. Deque Systems Inc. (n.d.). Axe DevTools. Retrieved April 21, 2023, from
hps://www.deque.com/axe/devtools/
19. Harrison, W. (2006). Eang Your Own Dog Food. IEEE Soware, 23(3), 5-7.
hps://doi.org/10.1109/MS.2006.72
20. DeadLinkChecker. (n.d.). Retrieved April 21, 2023, from hps://deadlinkchecker.com
21. Dr. Link Check. (n.d.). Retrieved April 21, 2023, from hps://www.drlinkcheck.com/
22. SHU Development Process. (n.d.). Feature Branches – Version Control. Retrieved April 21,
2023, from hps://aserg.codeberg.page/shu-dev-process/en/planning/version-
control/#feature-branches
23. Microso Corporaon. (n.d.). Playwright. Retrieved April 21, 2023, from
hps://playwright.dev/
24. Codeberg Community. (2023, April 10). Codeberg Pages. Retrieved April 10, 2023, from
hps://docs.codeberg.org/codeberg-pages/
25. Cloudare, Inc. (n.d.). Pages. Retrieved April 21, 2023, from hps://pages.cloudare.com/
26. Gitea. (2022, December 1). Gitea Acons. Retrieved April 21, 2023, from
hps://blog.gitea.io/2022/12/feature-preview-gitea-acons/
27. Storyblok GmbH. (n.d.). Storyblok. Retrieved April 21, 2023, from
hps://www.storyblok.com/home
28. Contenul GmbH. (n.d.). Contenul. Retrieved April 21, 2023, from
hps://www.contenul.com/
29. Sanity.io, Inc. (n.d.). Sanity. Retrieved April 21, 2023, from hps://www.sanity.io/
30. Forestry Labs, Inc. (2023, April 11). Tina CMS. Retrieved April 11, 2023, from hps://na.io/
31. Front Maer. (n.d.). Frontmaer CMS. Retrieved April 21, 2023, from
hps://frontmaer.codes/
32. Plausible Analycs AB. (n.d.). Custom Event Goals. Retrieved April 21, 2023, from
hps://plausible.io/docs/custom-event-goals
33. Plausible Analycs AB. (n.d.). Plausible. Retrieved April 21, 2023, from hps://plausible.io/
34. Redis Labs Ltd. (2021, December 6). What is Fuzzy Matching? Retrieved April 10, 2023, from
hps://redis.com/blog/what-is-fuzzy-matching/
35. OpenAI. (n.d.). ChatGPT. Retrieved April 21, 2023, from hps://chat.openai.com/
36. Google LLC. (n.d.). TensorFlow.js. Retrieved April 21, 2023, from
hps://www.tensorow.org/js
37. Microso Corporaon. (n.d.). ONNX Runme. Retrieved April 10, 2023, from
hps://onnxrunme.ai/
