diff --git a/chapters/0-introduction.tex b/chapters/0-introduction.tex index b55fe91..d884885 100644 --- a/chapters/0-introduction.tex +++ b/chapters/0-introduction.tex @@ -6,7 +6,7 @@ \chapter{Introduction} That is approximately 13.3 million people. In the physical world, companies are by law bound \citep{DDA} to ensure that this minority are able to access their services; be it by -leaving enough room to accomodate wheel chairs; or offering large text prints +leaving enough room to accommodate wheel chairs, or offering large text prints of their products. In the digital world there are no such laws and thus the web can be a difficult place for these users to consume services and content. @@ -14,10 +14,10 @@ \chapter{Introduction} tools aim to improve the experience by targeting a selection of disabilities and offering other means to consume the content. For example, JAWS \citep{JAWS} targets visually impaired users; reading the content, -labelling actions and offering keyboard shortcuts to navigate. The +labeling actions and offering keyboard shortcuts to navigate. The problem with all these tools is that they rely upon Software Engineers to produce -content semantically (using HTML, CSS and Javascript) and add metadata using, +content semantically (using HTML, CSS, and Javascript) and add metadata using, until recently, very loose specifications \citep{WCAG} to enable the tools to better process the content. @@ -27,20 +27,20 @@ \chapter{Introduction} This identifies a clear gap in knowledge within the design/development community when it comes to producing accessible web applications. -This project aims to to reduce the size of the gap by enabling the development +This project aims to reduce the size of the gap by enabling the development community through education and `easy to use' tools to think about and implement accessibility whilst coding. This report begins with a background chapter to discuss the topic, the business requirement, this projects goals and the methodology that will be used to -compelete it. Chapter 2 will discuss the first deliverable an +complete it. Chapter 2 will discuss the first deliverable an accessibility guide. It will document the preparation that was undertaken and -then then how the deliverable was designed and implemented. Chapter 3 will be +then how the deliverable was designed and implemented. Chapter 3 will be of similar structure, using the knowledge learned building the guide it will -discuss the creation of a tool for assessing accessibilty issues. A +discuss the creation of a tool for assessing accessibility issues. A critical evaluation of the project will follow discussing the successes -and shortcomings as well as personal reflections on the journey. Followed by -of course a concluding paragraph, references and appendecies. +and shortcomings as well as personal reflections on the journey. Finally, a +concluding paragraph, references, and appendices will end the report. % The Introduction should clearly lay out the principal motivation for the % project diff --git a/chapters/1-background.tex b/chapters/1-background.tex index 43280e3..b911589 100644 --- a/chapters/1-background.tex +++ b/chapters/1-background.tex @@ -8,7 +8,7 @@ \chapter{Background} \section{What is accessibility?} "Accessibility" is a subjective term which offers many opinionated -definitions. The \cite*{OxDict} defines accessiblity as: +definitions. The \cite*{OxDict} defines accessibility as: \begin{quote} "The quality of being able to be reached or entered" \end{quote} @@ -31,10 +31,10 @@ \section{What is accessibility?} used by individuals with disabilities" \end{quote} -Finally \cite*{JimByrne} founder of Guild of Web Designers offers an interesting +Finally, \cite*{JimByrne} founder of Guild of Web Designers offers an interesting insight. He refers to Google as a blind visitor which is technically correct as google will never be able to see all the `pretty' pictures on your website. -It can however understand text and markup. This hints at the fact that +It can however, understand text and markup. This hints at the fact that improving the markup will improve the experience for not just users of assistive tools, but machines too. @@ -43,14 +43,13 @@ \section{What is accessibility?} \end{quote} To me, accessibility is a way of thinking. It requires a range of disciplines -and should start with what the users goal is. If any type of user is unable to -acheive the goal they came to acheive then the web page is inaccessible. It -is unfortunately entirely possible to have the most semantic well -structured web page yet it is still totally inaccessible. +and should start with what the users' goal is. If any type of user is unable to +achieve the goal they came to achieve then the web page is inaccessible. It +is unfortunately entirely possible to have the most semantic well-structured web page yet it still be totally inaccessible. \section{Business Context \& Requirement} Capgemini undertakes a range of projects across both public and private -sector. In the current digital climate most projects involve the +sector. In the current digital climate, most projects involve the development of some form of web frontend. As a Professional Services supplier it is quite common for Software Engineers to be multi-skilled and thus web development may not be a ``core skill". A common problem is that developers @@ -61,7 +60,7 @@ \section{Business Context \& Requirement} These mistakes are only identified later in the project when 'assistive tool' testing is performed at which point repetitive and sometimes significant rework may be necessary. The agile 'Cost of Change' \citep{CostOfChange} curve -shown in Fig.~\ref{fig:costOfChange} demonstrates this. +shown in Fig.~\ref{fig:costOfChange} demonstrates the cost of a change as the time moves on in a project. \begin{figure}[H] \centering @@ -71,14 +70,14 @@ \section{Business Context \& Requirement} \label{fig:costOfChange}} \end{figure} -With this in mind this project aims to enable developers with limited +With this in mind, this project aims to enable developers with limited experience in web development to write cleaner, more semantic code. It is -through educating developers that the primary goal of offering a better +through educating developers that offering a better experience to users of assistive tools can be achieved. By building a tool that can be used during -the development process the feedback loop on issues will be much +the development process, the feedback loop on issues will be much shorter and as described in agile 'cost of change' the cost of remediation much lower. The tool will be supported by an accessibility guide which can be used either to teach or to reference when trying to understand. @@ -113,7 +112,7 @@ \section{Business Context \& Requirement} importance to those that use rely on it would be a great benefit to Capgemini’s developers and the developer community as a whole. If these guidelines could be distilled into the kind of language that has become commonplace for -explaining other areas of front end development, it would help to dispel +explaining other areas of front-end development, it would help to dispel myths of complexity and allow projects to implement WCAG in a meaningful way. This would save on project costs by removing pitfalls of “adding it later”; but importantly, it would help to keep the web a diverse and inclusive place."} @@ -126,7 +125,7 @@ \section{Project Goals} the project deliverables will be relevant, useful and fill the described business need. The deliverables are: \begin{enumerate} - \item A tool for software engineers which will bootstrap itself into a web + \item A tool for software engineers which will bootstrap itself into the web browser, assess and report possible accessibility issues \item A suite of documentation which will collate and demonstrate best practices. It will show what 'assistive tools' output based upon different @@ -141,7 +140,7 @@ \section{Project Stakeholders} \item My two supervisors — Academic and Company, these are the people whom the deliverables will be presented too. \item Software Engineers at Capgemini — To improve the experience for the - users web developers \& designers are those who need to produce a better + user's web developers \& designers are those who need to produce a better product. \item Software Engineers within the wider community - Similar to above \item Users of assistive technologies. This whole project would be @@ -165,7 +164,7 @@ \section{Methodology} the project. 'Medium' \citep{Medium} a blogging platform will instead be used to capture key events and entries. At the end of the project this will be - supplemented with notes from meetings between myself and my acadamic + supplemented with notes from meetings between myself and my academic supervisor. %TODO - Check with HARRY if the below statement is correct. This is %TODO currently an assumption and may be totally incorrect. @@ -177,7 +176,7 @@ \section{Methodology} feedback' from stakeholders and produce a higher quality product \item Open Source Everything - Capgemini consumes and produces a lot of open source software! With myself sitting within a team - that are leading this drive, all code produced will be available under a MIT + that are leading this drive, all code produced will be available under an MIT Licence \citep{MITLicence} on Github. \item Share Everything - The JVM team has its own 'ethos' \citep{JVMHowWeWork} that sits on top @@ -190,7 +189,7 @@ \section{Methodology} things tackled on each deliverable. This will allow its process to be tested and validated - for every change made thereafter; reducing risk of failure later in the + for every change made thereafter; reducing the risk of failure later in the project. Travis CI \citep{TravisCi} and Github Pages \citep{Ghpages} will enable this. @@ -198,7 +197,6 @@ \section{Methodology} \subsection{Making Better Decisions} \label{sec:manifesto} -% TODO * reference Agile Manifesto Coming from a background in Agile projects, the ``Agile Manifesto" \citep{AgileManifesto} has enabled me to make and justify difficult decisions under pressure. For example deciding @@ -226,18 +224,18 @@ \subsection{A Process} This project is no exception and will follow the Unified Process. This gives a structure to different phases throughout the lifecycle of -the project Inception, Elaboration, Construction and Transition. It enables +the project Inception, Elaboration, Construction, and Transition. It enables iterations to occur within each of these phases but focuses the iteration towards the goal of the phase you are currently in. \subsubsection{Why the Unified Process?} Agile is a poor fit for me as a distant learner with a -full time job. Each iteration requires a small amount of every aspect of the +full-time job. Each iteration requires a small amount of every aspect of the development lifecycle (analysis, design, implementation and test). This would make it difficult to understand and report progress to myself and the -stakeholders. Given the projects deliverables are well known from -the outset Agile would only add unneccesary ceremonies. +stakeholders. Given the deliverables are well known from +the outset Agile would only add unnecessary ceremonies. Using the manifesto above, the sprial model would satisfy ``Start simple with many organic iterations", due to each turn of the spiral gaining user feedback @@ -245,11 +243,11 @@ \subsubsection{Why the Unified Process?} and well structured for this project. What steered the project towards Unified Process over Spiral was the amount of risk collection and analysis required. Due to being an individual project, most -risks fall into the low probability, low impact category, and with one quater of -each spiral dedicated to risk analysis . +risks fall into the low probability, low impact category, and with one quarter of +each spiral dedicated to risk analysis. -\subsection{High Level Planning} -At a high level I was aiming for the following to be acheived: +\subsection{High-Level Planning} +At a high level I was aiming for the following to be achieved: \begin{enumerate} \item {Inception - February} \begin{itemize} @@ -286,7 +284,7 @@ \subsection{High Level Planning} \end {enumerate} \section{A Major Issue} -Due to unforseen circumstances \textasciitilde6 weeks of time was lost; +Due to unforeseen circumstances \textasciitilde6 weeks of time was lost; Mid-March through to the start of May. This covered the Elaboration, and Construction phase of the project. So it was clear a change in process would be necessary. @@ -295,7 +293,7 @@ \subsection{Change of process} I chose to change from the 'Unified Process' towards a more prototypical/iterative process; 'Evolutionary Prototyping'. This is a form of the prototyping model which often suits tight time scales and fast development -lifecycles \citep{EvoProto}. The 'Evoloutionary' aspect means rather than the +lifecycles \citep{EvoProto}. The 'Evolutionary' aspect means rather than the prototype being thrown away and rebuilt at the end, it will instead be iteratively enhanced until a final product is produced. Fig.~\ref{fig:proto} from \citep{EvoProto2} displays the process. diff --git a/chapters/2-a11y-guide.tex b/chapters/2-a11y-guide.tex index 449fd1c..163a4ce 100644 --- a/chapters/2-a11y-guide.tex +++ b/chapters/2-a11y-guide.tex @@ -5,7 +5,7 @@ \end{savequote} \chapter{A11Y Guide} -In preperation for the main deliverable a deeper level of knowledge in the +In preparation for the main deliverable, a deeper level of knowledge in the accessibility space was required. To gain this knowledge and inline with my `Share Everything' approach it was decided that an `Accessibility training guide' would be produced here on referred to as `A11Y guide'. The idea @@ -16,7 +16,7 @@ \section{Preparation} \subsection{Planning} As researched by \citep{Ebbinghaus} in 1885 the forgetting curve demonstrates the amount of knowledge remembered after a period of time. See Fig.~\ref{fig:ebbinghaus} -Repeating or revising the learning unsuprisingly results in the knowledge +Repeating or revising the learning unsurprisingly results in the knowledge stored in memory for longer. \begin{figure}[H] @@ -27,14 +27,14 @@ \subsection{Planning} \label{fig:ebbinghaus}} \end{figure} -With this in mind I plan to iteratively build the A11Y Guide so +With this in mind, I plan to iteratively build the A11Y Guide so that the knowledge will be reinforced. The steps for its production will be as follows: \begin{enumerate} \item Search for useful resources online (First time learning) \item Score the identified resources with the assistive tools for a first hand experience along with other criteria (Second time repeating) - \item Collate the resources under the correct header in a github project + \item Collate the resources under the correct header in a Github project \item Setup continuous deployment scripts to ensure deploy on commit \item For each header create and document best practices (Third time repeating) @@ -42,7 +42,7 @@ \subsection{Planning} \item For each header create coded examples (Fourth time repeating) \end{enumerate} -As explicitly stated there will be four loops of observing, reviewing and +As stated there will be four loops of observing, reviewing and applying the knowledge learned which should result in a peak in knowledge when producing the tool. @@ -55,15 +55,15 @@ \subsection{Building A11Y Guide Requirements} \subsubsection{Understanding industry movement} \label{sec:uim} The purpose of understanding the current industry is to ensure that the -content within the guide is relevant and inline with the current status of the -industry. By understanding where the industry had come from and where it was -going would enable me to filter `old' resources from `new' resources and thus +content within the guide is relevant and aligned with the current status of the +industry. By understanding where the industry has come from and where it is +going will enable me to filter `old' resources from `new' resources and thus produce more relevant guidance. See \ref{sec:GatheringKnowledge} for more detail on the collection phase. Being an apprentice within the industry I have exposure to general movements -and directions (through colleagues and self found sources), but primary -evidence was required to back up my personal opinion. +and directions (through colleagues and self-found sources), but primary +evidence was required to back up my theories. In 2016 the largest survey ever of front end developers was completed the 'State of JS' \citep{StateOfJs}. This survey covered almost every aspect of the front end @@ -80,13 +80,13 @@ \subsubsection{Understanding industry movement} Based on my constant technology tracking I hypothesised that the technologies that were `Used it before, would use again' and `Heard of it, would like to -learn' were the big winners in 2017. In Javscript frameworks this was ReactJs +learn' were the big winners in 2017. In Javascript frameworks, this was ReactJs and Angular 2. Again this needed clarification so I chose to use `Google Trends' \citep{GoogleTrends} a tool which allows users to view graphs of search queries on a -relative scale. During development most software engineers will +relative scale. During development, most software engineers will refer to google for documentation and issues so I felt this was going to be a -sound method for determining this. Fig.~\ref{fig:js_compare} confirms my +sound method for determining the direction. Fig.~\ref{fig:js_compare} confirms my hypothesis and shows how ReactJS overtook AngularJS with Angular 2 on the rise. \begin{figure}[H] @@ -100,12 +100,7 @@ \subsubsection{Understanding industry movement} \end{figure} \subsubsection{Questionnaire} -% TODO -% - Reference Professional competency scale https://hr.od.nih.gov/workingatnih/competencies/proficiencyscale.htm -% - Reference Remote working Capgemini -% - Reference google forms - -The questionnaire's purpose is to understand the frameworks, components and +The questionnaire's purpose is to understand the frameworks, components, and competencies in use across Capgemini. The next three paragraphs describe what I want to discover and why. @@ -122,15 +117,15 @@ \subsubsection{Questionnaire} The level of competency developers have in accessibility \ref{q:6}. This will help understand the level at which to pitch the guidance (The target audience) -and will answer the question ``What level of competency can be assumed?". My +and will answer the question ``What level of competency can be assumed?". The aim is to use the National Health competency scale \citep{NHComptency} to -asses this. +assess this. Google Forms was used to implement the questionnaire due to its simple setup and integration into Google Spreadsheets which made the following analysis much easier. -Out of a possible 69 team members 40\% (26 members) responded. +Out of a possible 69 team members, 40\% (26 members) responded. The first two questions showed how most software developers are using or are competent in either React or AngularJS. This with the fact that @@ -139,9 +134,8 @@ \subsubsection{Questionnaire} recommendations made with this in mind. It is a fair assumption that developers competent in React should be able to apply the knowledge learned to Angular JS. Fig.~\ref{fig:current_proj} and Fig.~\ref{fig:competent_in} -are bar charts of the results given. A suprise discovery was the popularity -of JQuery. This is likely due to its widespread usage historically as it is -slowly becoming legacy. +are bar charts of the results given. A surprise discovery was the popularity +of JQuery. This is likely due to its widespread usage historically as it is becoming legacy. \begin{figure}[H] \centering @@ -162,15 +156,15 @@ \subsubsection{Questionnaire} \end{figure} The next two questions focussed on understanding the software components in -use across client projects. An important aspect of many of our clients user base +use across client projects. An important aspect of many of our client's user base is data entry and it is vital that users of assistive tools can interact and understand these. The first question revolved around this and asked ``What form components are in use on your current project?". The next question was targeting more data consumption and higher level components so asked ``What web components are in use on your project". -Unsuprisingly of the form components Fig.~\ref{fig:form_components}, textual -inputs (23/26 respondants) were the highest with select menus (22/26) and +Of the form components Fig.~\ref{fig:form_components}, textual +inputs (23/26 respondents) were the highest with select menus (22/26) and validation messages (20/26) close behind. These would therefore be completed first in the A11Y guide. @@ -183,11 +177,11 @@ \subsubsection{Questionnaire} \label{fig:form_components}} \end{figure} -At a data consumption level there was a small anomoly in the data. `Images' -had accumulated 27/26 respondants. Due to the small sample size I dug into the +At a data consumption level, there was a small anomaly in the data. `Images' +had accumulated 27/26 respondents. Due to the small sample size I dug into the raw data and discovered that the `Images' option appeared twice on the possible answers. With manual counting of this value, the correct number -of respondants was actually 17/26. +of respondents was actually 17/26. With images now normalised Navbars, Tabs, and Images all had 17/26 usages. These were shortly followed by Dialogs (16/26) and Tables (16/26). Fig @@ -202,7 +196,7 @@ \subsubsection{Questionnaire} \label{fig:components_in_use}} \end{figure} -The final quesion asked each individual to rate themselves on the National +The final question asked each individual to rate themselves on the National Health competency scale \citep{NHComptency}. I added some additional guidance to the different levels to try and get a consistent answer across the participants. @@ -216,8 +210,8 @@ \subsubsection{Questionnaire} \item Expert - The `go to' person for web accessibility \end{itemize} -Due the questionnaire being anonymous it is a fair assumption that honest -answers are more probable. It is interesting how 18/26 ~70\% of respondants +Due to the questionnaire being anonymous it is a fair assumption that honest +answers are more probable. It is interesting how 18/26 ~70\% of respondents have had no experience with the testing tools and rely upon Google to understand accessibility. Fig.~\ref{fig:a11y_level} once again highlights the requirement a project around accessibility is required at Capgemini. @@ -243,8 +237,8 @@ \subsubsection{Method} however, after reviewing resources in `Links' and `Buttons' items which I am personally familiar with. I found a lot of overlap between content and after testing them with the tools, similar mistakes across all of them. -None seemed to capture the `why' which naturally meant I needed a -different method. +None seemed to capture the `why' which naturally a +different method was needed. To produce a new method I started by understanding what I needed to know to produce the content. By understanding this I would be able to produce a method @@ -260,14 +254,14 @@ \subsubsection{Method} \end{itemize} I produced 10 questions each with a possible score of 10. I was looking to -use the three best scoring resources in my content. +use the three best scoring resources in the A11Y Guide content. \subsubsection{Example Scoring} \subsubsection{Outputs} Inline with my `Open Source' and `Share Everything' ethos the resources were -sorted based upon their content and placed upon my github account in a public +sorted based upon their content and placed upon my GitHub account in a public repository. See Fig \ref{fig:allyLinksDemo}. Following the principles of Continuous Delivery this could in fact be @@ -300,7 +294,7 @@ \subsubsection{Defining Requirements} \hline I want to have a section highlighting the most important aspects I need to take on board \\ - So that when I can quickly apply them on my current project \\ + So that I can quickly apply them on my current project \\ \hline I want to have coded examples written in React \\ So that I can understand and apply the knowledge \\ @@ -316,20 +310,20 @@ \subsubsection{Defining Requirements} \section{Deliverable} \subsection{Iteration 1 - Create content using markdown} -The first iteration of developing content was targetted the broader aspects -which affect every part of the users experience. This covered page structure, +The first iteration of developing content was targeting the broader aspects +which affect every part of the user's experience. This covered page structure, page content and other general aspects like typography and colour. The content was produced using Markdown \citep{Markdown}. \subsubsection{Why Markdown?} Markdown was chosen as it is fast becoming the `developer standard' for writing documentation. When producing content, familiarity is key to producing an -enviornment in which people will collaborate. If you first have to +environment in which people will collaborate. If you first have to learn a new language or tool the barrier to entry to produce the content is higher and thus you are less likely to do it. As Github the `worlds biggest' \citep{GithubBig} software control platform has bought into markdown as way developers communicate `most' developers have at least some knowledge in the -area. If they do not, the documentation for using markdown is well estabilished. +area. If they do not, the documentation for using markdown is well established. An additional benefit to using markdown is it is relatively difficult to make the content you produce ``Inaccessible". As I want the guide to demonstrate @@ -337,8 +331,8 @@ \subsubsection{Why Markdown?} great at transforming content into `assistive tool' friendly HTML. Fig \ref{fig:hierarchy} and Fig \ref{fig:structures} demonstrates how the -content is displayed in github's standard folder view. The markdown text is -converted into HTML and displayed in a clear well structured manner. +content is displayed in Github's standard folder view. The markdown text is +converted into HTML and displayed in a clear well-structured manner. \begin{figure}[H] \centering @@ -364,7 +358,7 @@ \subsection{Iteration 2 - UI Design \& Build site} into an easily consumable website. Using this content and the requirements set out in \ref{sec:requirements} the design would need to support: \begin{itemize} -\item Coded Examples (Prefferably with snippet highlighting) +\item Coded Examples (with snippet highlighting) \item Snippets of the assistive tools reaction to good/bad markup \item Navigation for a hierarchical structure \item The best practices it describes @@ -390,7 +384,7 @@ \subsection{Iteration 2 - UI Design \& Build site} reused by abstracting the framework away from the content itself. For a user of the documentation framework, I wanted them to only have to edit the content and/or the Table of Contents. This would enable content to be the -users main focus and thus speed up the development of content for the guide. +user's main focus and thus speed up the development of content for the guide. \begin{figure}[H] \centering @@ -418,7 +412,7 @@ \subsection{Iteration 2 - UI Design \& Build site} The web app was built using 'create-react-app' \citep{CreateReactApp} a tool built by facebook for enabling the quick production of React web applications. When the CLI tool runs it generates a basic web application with some sample -code. To reduce the risk later and following the continous delivery +code. To reduce the risk later and following the continuous delivery guidelines \citep{ContinuousDelivery} I decided now was a good time to set up my deploy pipeline. Fig.~\ref{fig:cd_pipeline} demonstrates the pipeline through a sequence diagram. @@ -436,7 +430,7 @@ \subsection{Iteration 3 - Continue content} As described by the title this iteration focussed on producing more content; specifically around the forms and components identified in the questionnaire. With the continuous deployment pipeline setup changes were instantly -consumeable at \url{https://geeman201.github.io/geemans-a11y-guide/} +consumable at \url{https://geeman201.github.io/geemans-a11y-guide/} \subsection{Iteration 4 - Recognise/Implement custom pages} \label{sec:iteration_4} diff --git a/chapters/3-a11y-tool.tex b/chapters/3-a11y-tool.tex index bf50bdf..6fb73bb 100644 --- a/chapters/3-a11y-tool.tex +++ b/chapters/3-a11y-tool.tex @@ -20,21 +20,21 @@ \subsection{Current Process} on in the project. Fig.~\ref{fig:process_1_} and Fig.~\ref{fig:process_2} demonstrate two slightly different methods projects go down. The common problem is that issues are only detected late in the development lifecycle. -The problems that are found tend to be similar and remdiation is often a +The problems that are found tend to be similar and remediation is often a painfully repetitive process. \subsection{Current solutions} \label{sec:currentSolutions} -With this in mind a survey of the current landscape of accessiblity tools was +With this in mind, a survey of the current landscape of accessibility tools was undertaken. Fortunately when producing the A11Y guide a list of current testing tools had been collated which made this step relatively easy. -Of the tools each plugs into different possible points throughout the +Of the tools, each plugs into different possible points throughout the development phase: \begin{itemize} \item The IDE - Most modern IDE's have a means for plugging in linting tools to check structure. - \item The CLI - Rulset libraries such as ESLint and HTMLLint can execute + \item The CLI - Ruleset libraries such as ESLint and HTMLLint can execute against your code and report issues to the console. They can even be part of a wider continuous integration setup \item The Browser - By bootstrapping through a `Bookmarklet' this method @@ -42,7 +42,7 @@ \subsection{Current solutions} \end{itemize} Performing more research into how the IDE tools work they are typically just -wrappers around. The table below shows the good/bad points surrounding each tool +wrappers around the CLI tools. The table below shows the good/bad points surrounding each tool \begin{table}[h!] \centering @@ -93,11 +93,11 @@ \subsection{Requirements} I want to be able to have errors categorised \\ So that I can prioritise which ones to fix first \\ \hline - I want remdediation advice \\ + I want remediation advice \\ So that I know how to fix the error \\ \hline I want remediation advice to have more information \\ - So that I can learn about the mistake made \\ + So that I can learn from the mistake made \\ \hline (This Project Scope) \\ I want 20\% of issues on BBC's terribly accessible page to be identified \\ @@ -121,14 +121,14 @@ \subsection{Proposed Solution} \label{fig:tool_current_design}} \end{figure} -With this in mind the design for this tool would focus on reusability and +With this in mind, the design for this tool would focus on reusability and customisation. Coming from a Java background we tend to apply the inversion of control principle \citep{DRC} to help decouple the reusable components from the specific ones. This comes with the added benefit of being able to build and test specific modules in isolation. -Fig.~\ref{fig:tool_proposed_design} demonstrates the high level design for +Fig.~\ref{fig:tool_proposed_design} demonstrates the high-level design for how this will be applied to the A11Y Tool. Components shown in grey demonstrate -the possiblites which are opened by using such a design but are out of scope +the possibilities which are opened by using such a design but are out of scope of this project. The next few sections in the report will document the design and implementation of each of the components within scope of the project. @@ -148,14 +148,14 @@ \subsection{A11Y Core} \subsubsection{Versioning} Due to other components relying upon A11Y Core's interfaces, versioning of -the api it exposes is important to ensure dependent parties are able to update +the API it exposes is important to ensure dependent parties are able to update efficiently. There are many versioning strategies available and most work on a form of three digits [major].[minor].[patch]. I always use `Semantic Versioning' \citep{Semver} due to the clear definition of when each number should increment. Patch for bug fixes and non api changes, Minor for API additions which are -backwards compatible and Major when a breaking API change is introduced. Due to this -clarity it is slowly becoming the defacto standard for software development +backward compatible and Major when a breaking API change is introduced. Due to this +clarity, it is slowly becoming the de-facto standard for software development so is likely to be familiar to others. \subsubsection{Checker} @@ -203,7 +203,7 @@ \subsubsection{Result} remediation which is to be added by the `Checker' to offer a recommended method to fix the identified issue. This coupling allows for the remediation to be specific to the exact issue found by the checker. Fig -.~\ref{fig:result_design} demonstrates `Results' inheritance structure. It is +.~\ref{fig:result_design} demonstrates the `Result' inheritance structure. It is unlikely that anyone would extend `Result' but similar to above it has been implemented with interfaces. @@ -218,14 +218,14 @@ \subsubsection{Result} \subsubsection{Worker} The concept of a `Worker' was added late on during the implementation phase as a direct result of the performance of `Checker's being poor. Performance issues -were noticeable when iterating around a web pages with a large number of DOM +were noticeable when iterating around web pages with a large number of DOM elements. The worker inverted the for loop and meant that rather than iterating around the DOM within each `Checker' The DOM was -iterated around only once and each checker was called to perform it's check +iterated around only once and each checker executed to perform its check only if that DOM node was relevant to it. `Workers' implement the Singleton Pattern so `Checkers' can be registered from -anywhere. Each individual checker registers itself with it's retrospective +anywhere. Each individual checker registers itself with its retrospective worker. The result of such a design (and the reason this was chosen over others) is that when a `Checker' is imported into a file it is registered with 'A11Y Core' and thus available for use. Fig.~\ref{fig:a11y_tool_worker_design} @@ -256,7 +256,7 @@ \subsection{A11Y WCAG Checker Pack} \end{lstlisting} \subsection{A11Y Browser} -The browser component enables the tool to be ran within a web browser. Fig +The browser component enables the tool to be run within a web browser. Fig .~\ref{fig:a11y_tool_browser_design} shows how this fits in with the other components. @@ -276,9 +276,9 @@ \subsubsection{Designing the UI} to satisfy were defined: \begin{itemize} -\item Highlight the html error in place (HTML Code sniffer does this) +\item Highlight the HTML error in place (HTML Code sniffer does this) \item Categorise errors in error/warning/info (Tota11y does this) -\item Display remdiation (None do this) +\item Display remediation (None do this) \item Have links to the A11Y guide to learn more about the issue \end{itemize} @@ -309,14 +309,14 @@ \subsubsection{Designing the UI} error back to the code in my IDE. I knew the HTML with the error but without the context of its surrounding elements its difficult to tie it back to the original source especially when using libraries like React and Angular. -Unfortunately most browsers deliberately limit access to devtools from +Unfortunately, most browsers deliberately limit access to devtools from javascript. I hypothesised that web developers code web apps with the 'devtools' open. To clarify this I put a message on our internal slack. -Asking people to agree/disagree with the statement. 8 'agreed' and 1 'disagreed'. -From this I decided that the best way to give the context would be to print -the html element to the devtools console. when the element is clicked it takes -the developer to the element in the page source. Similarly advice and -remeidation were also posted here as shown in \ref{fig:remediation} +Asking people to agree/disagree with the statement. 8 'agreed' and 1 'disagreed'. Confirming my hypothesis. +From this, I decided that the best way to give the context would be to print +the HTML element to the devtools console. When the element is clicked it takes +the developer to the element in the page source. Similarly, advice and +remediation were also posted here as shown in \ref{fig:remediation} \begin{figure}[H] \centering @@ -327,34 +327,34 @@ \subsubsection{Designing the UI} \end{figure} \subsubsection{Bootstrapping the browser} -For the tool to run script tags need to be loaded into the browser. The traditional means is via a +For the tool to run, script tags need to be loaded into the browser. The traditional means is via a 'Bookmarklet' these sit in the bookmark/favourite bar of a users browser and when clicked execute javascript on the users web page to insert the tag and load the tool. -Unfortunately due to Cross Site Scripting issues browsers are implementing -content restrictions whereby the browser blocks scripts from a -domains excluded from a specific meta tag list. When all browsers support +Unfortunately, due to Cross Site Scripting issues browsers are implementing +content restrictions \citep{bookmarklets} whereby the browser blocks scripts from domains +excluded from a specific meta tag list. When all browsers support content restrictions the tool would no longer function. An alternate approach was required and two methods were explored to solve this. The first a 'browser extension' which would require a small wrapper around the A11Y Browser tool for each individual browser. This solved the problem. -The tool was loaded into the users browser and worked as expected but a -wrapper would be require packaging for each indivdual browser and there is -talk that vendors are phasing out extensions. +The tool was loaded into the user's browser and worked as expected but a +wrapper would be require packaging for each individual browser and there is +talk that vendors are phasing out extensions \citep{chromeapps}. -The second, and chosen method, was by allowing the script tag to be inserted -at development time through a script tag. Users could add this to the html +The second, and chosen method was by allowing the script tag to be inserted +at development time through a script tag. Users could add this to the HTML file they wished to test. \subsection{Testing} \subsubsection{Enabling others} -With the tool mainly exposing a means for others to plugin and create custom +With the tool mainly exposing a means for others to plug in and create custom accessibility `checkers' it was important to demonstrate how developers can -write tests to confirm their checkers. With this in mind a small collection +write tests to confirm their checkers. With this in mind, a small collection of utility methods were created. The aim of these was to reduce the amount of -boiler plate required to write the tests. For example when creating dom +boilerplate required to write the tests. For example when creating dom elements a test initially looked similar \ref{lst:before}. \begin{lstlisting}[label={lst:before}] it('should expect only A elements: Negative test', () => { @@ -364,7 +364,7 @@ \subsubsection{Enabling others} \end{lstlisting} But I kept on finding I was forgetting to add the .getDomNode on the end of -the call to create the component. This therefore became a candidate for +the call to create the component. This therefore, became a candidate for extraction. The effect was a much cleaner syntax as demonstrated below. \begin{lstlisting}[label={lst:before}] @@ -378,13 +378,13 @@ \subsubsection{Enabling others} \subsubsection{The A11Y tool} Unit testing of the tool was completed using Jest \citep{jest} with jasmine \citep{jasmine}. These are two frameworks which interlink well -together and offer a simple means to drive web based APIs. Below is a snippet -of some tests for a HREF Checker whos purpose is to check anchor html elements +together and offer a simple means to drive web-based APIs. Below is a snippet +of some tests for a HREF Checker whose purpose is to check anchor HTML elements for correct href attributes. Note how each test increases the functionality expected of the checker which -enables checking of regressions every time it is excuted. This model was -applied accross most of the code base. +enables checking of regressions every time it is executed. This model was +applied across most of the code base. \begin{lstlisting} describe('The Link Checker should', () => { diff --git a/chapters/4-evaluation.tex b/chapters/4-evaluation.tex index d8e4fa2..ad344d3 100644 --- a/chapters/4-evaluation.tex +++ b/chapters/4-evaluation.tex @@ -7,7 +7,7 @@ \chapter{Evaluation} This chapter will provide a critical evaluation of the projects journey and -the deliverables that were produced. In terms of following a method each +the deliverables that were produced. In terms of following a method, each deliverable will be evaluated using my manifesto (Section \ref{sec:manifesto}) and the following questions: \begin{enumerate} @@ -41,13 +41,13 @@ \subsection{Meeting requirements} \begin{center} \textit{``I want to have coded examples written in React"} \end{center} -Due to the nature of the topic this requirement is difficult to -measure. Most of the examples written used react as a means to demonstrate +Due to the nature of the topic, this requirement is difficult to +measure. Most of the examples written used React as a means to demonstrate good and bad practice. An improvement that I worked in during Iteration 4 was to enable the documentation framework to embed examples. This was really impactful as it enables developers to see the code, the result, and the snippet of the tool. -A problem I had was it was difficult to pitch a `component' at the write +A problem I had was it was difficult to pitch a `component' at the right level for users as I was unsure what they would do with it. Would they use it as is? Would they just take the HTML? Would they just read and understand it? Perhaps some additional @@ -57,10 +57,10 @@ \subsection{Meeting requirements} \begin{center} \textit{``I want to have assistive tool examples of different markups"} \end{center} -This was implemented mainly through subtitles in the side bar as shown in Fig -.~\ref{fig:a11y_guide_assistive_tool_snippet}. I felt it demonstrated really well the difference +This was implemented mainly through subtitles in the sidebar as shown in Fig +.~\ref{fig:a11y_guide_assistive_tool_snippet}. I felt it demonstrated the difference in what applying good semantics can make to the experience of assistive -tools. The deliverable faultered in demonstrating tools other than those for +tools. The deliverable faltered in demonstrating tools other than those for the visually/motor impaired. By including examples from other tools a richer understanding could have been given. @@ -80,7 +80,7 @@ \subsection{Meeting requirements} collection of at least three useful links was included. Because I followed a method for collecting the resources (Section \ref{sec:GatheringKnowledge}) and in many cases used them myself to understand various topics I am confident -that thier content is of high quality. +that their content is of high quality. In hindsight assessing each link in this way was extremely time consuming and resulted in only slightly better content. But it means the guide makes a good @@ -88,13 +88,13 @@ \subsection{Meeting requirements} \subsection{Impact} \subsubsection{Personal \& Business} -From a personal level I have found this deliverable extremely useful! I +From a personal level, I have found this deliverable extremely useful! I actively use the content and best practices it documents in most of my day to day work. When discussing with colleagues accessibility and my expertise on accessibility I have been able to refer to this to backup claims and suggestions I make. -From a business perspective the guide targets the frameworks and components +From a business perspective, the guide targets the frameworks and components which are used across current Capgemini projects. The real impact will only be seen as a greater period of time goes by. Tom Brown a 'Test lead` said the following about the guide and its contents. @@ -103,12 +103,12 @@ \subsubsection{Personal \& Business} \textit{``The guide gives a great overview of how to fix the common issues we often identify during assistive tool testing. Typically when we show developers how the tools behave they are keen to fix the problems they have made. It is -good to see the demosntrations of how the tools behave."} +good to see the demonstrations of how the tools behave."} \end{center} Being an employee of Capgemini and this work been available in the public domain it is possible that this work will result in a reputation gain as -Capgemeni being a 'leader' in accessible research and writing inclusive +Capgemini being a 'leader' in accessible research and writing inclusive software. \subsection{Future} @@ -126,16 +126,16 @@ \subsection{Meeting requirements} \end{center} Through the introduction of `checker packs' this requirement has been achieved. A checker pack is defined through a single Javascript which uses -ES6 import statements although realtively clean an alternate 'nicer' way in -which these could have been achieved was through a json file +ES6 import statements although relatively clean an alternate 'nicer' way in +which these could have been achieved was through a JSON file \begin{center} \textit{I want to be able to run the tool through multiple methods} \end{center} Evidence of this being possible is relatively limited but the high level design of the tool demonstrates how it could be done. With A11Y Core being -seperate to A11Y Browser wrapping the core module in a CLI runner for tools -like jenkins should relatively easy. +separate to A11Y Browser wrapping the core module in a CLI runner for tools +like Jenkins would be relatively easy. \begin{center} \textit{I want to be able to have errors categorised} @@ -170,7 +170,7 @@ \subsection{Next time} the report and product produced. One of the areas I accumulated technical debt in was the testing of the tool. I did some manual testing of the A11Y Browser component, and wrote unit tests around the checkers but very -little of the A11Y Core. To me the design feels sound, but the product +little of the A11Y Core. To me, the design feels sound, but the product relatively immature. If I were to deliver this project again with the same incidents and time @@ -185,7 +185,7 @@ \subsection{Impact} \subsection{Future} With the work that has gone into designing/developing the tool thus far I believe the ideas and implementation are extensible and could sit as an -alternative to some of the more well known tools. Following this project I am +alternative to some of the more well-known tools. Following this project I am hoping to continue its development into a more solid product. @@ -212,7 +212,7 @@ \subsection{Colour Contrast Tool} identified a gap for a ``modern", user focussed tool. Most current tools require submission to a server and lack demonstrations of what the two colours look like when used together \cite*{JuicyStudio}. All -of them satisfied a relatievly simple set of requirements: +of them satisfied a relatively simple set of requirements: \begin{itemize} \item Report the colour contrast level between two distinct colours \item Report whether the colours contrast level of such colours satisfies the @@ -237,10 +237,10 @@ \subsection{Colour Contrast Tool} The `Happy Day' user journey would be: \begin{itemize} -\item User enters first colour in input field (Can paste) +\item User enters the first colour in input field (Can paste) \item User enters second colour in input field \item On a valid colour entered. Both are displayed as background and -foreground; the value of colour contrast is displayed; and the contrast +foreground; the value of colour contrast is displayed, and the contrast levels WCAG appropriateness is displayed in the circles. Green for success, Red for failure. \end{itemize} @@ -249,7 +249,7 @@ \subsection{Colour Contrast Tool} colours would remain the same and the input field would have a `red' background and border to signify an error. -This was deployed through github pages to \url{https://colour-contrast.github.io/} +This was deployed through GitHub pages to \url{https://colour-contrast.github.io/} and was tweeted about by myself and subsequently the creator of 'styled-components'. In the month the tool has been live it has gained \textasciitilde450 views across most @@ -266,24 +266,22 @@ \subsection{Colour Contrast Tool} \section{Ways of working} This is an area of the project which probably experienced the most -experimentation, problems and successes. +experimentation, problems, and successes. \subsection{Project Diary} `Medium' was used to blog the journey and significant events that -occured throughout the project. I did this to produce a level of transparency +occurred throughout the project. I did this to produce a level of transparency between myself, my supervisors and the wider Capgemini community. In -acheiving that goal I think it did a great job. To start with each post was +achieving that goal I think it did a great job. To start with each post was targetted towards individual items of `progress' with titles such as 'The -Manfesto' and `Snapshot of web frameworks'. However, I realised that this +Manifesto' and `Snapshot of web frameworks'. However, I realised that this wasn't really a `diary' of events that happened and would not be sufficient -to fulfil the role of the project diary. +to fulfill the role of the project diary. I decided to change the format into a weekly update -detailing a summary of what happened followed by in depth notes about +detailing a summary of what happened followed by in-depth notes about anything that had been delivered that week. It was great to be able to send -these to my supervisors and helped to keep the project on track. I -think this was because commitments -made in were publically available and thus to me became higher priorty. +these to my supervisors and helped to keep the project on track. All blog posts are available at \url{https://medium.com/@Geeman201/}. Below is an example of the most popular post `March 2017 - Web Framework Snapshots' @@ -297,13 +295,13 @@ \subsection{Project Diary} \label{fig:medium_example}} \end{figure} -Towards the end of the project these became less frequent and eventually +Towards the end of the project, these became less frequent and eventually fizzled out due to the pressures around delivering the project. \subsection{Planning} -At the start of my project I planned to use trello as a means of tracking what +At the start of my project, I planned to use Trello as a means of tracking what needed to be done, what was in progress and what had been completed. My aim was to use a kanban like approach and limit the work in progress to a single item. In the hope of focussing me to work on a single thing at a time. After @@ -311,9 +309,9 @@ \subsection{Planning} the project from a notepad which I was able to use in offline environments. I felt that this turned out to be effective given my circumstances. Trello -just seemed to be hindering me. With a notepad I was able to -document thoughts, discussions and actions whilst at work. Where as with -trello I would have had to hold those until the end of the day before they +just seemed to be hindering me. With a notepad, I was able to +document thoughts, discussions, and actions whilst at work. Whereas with +Trello I would have had to hold those until the end of the day before they could be written down. \subsection{Manifesto \& Methodology} @@ -345,13 +343,13 @@ \subsection{Manifesto \& Methodology} \begin{center} \textit{``Start simple with many organic iterations" over ``Upfront design"} \end{center} -Similar to above the A11Y Guide was the perfect example of this. THe +Similar to above the A11Y Guide was the perfect example of this. The iterations were clearly defined and well planned. The content was produced -first, the web site on top of the content was then produced and each -iteration improved on the inital product. +first, the website on top of the content was then produced and each +iteration improved on the initial product. I feel the A11Y tool was a bit more of a `big bang' approach. More upfront -design probably would have resulted in better defined iterations and maybe a +design probably would have resulted in better-defined iterations and maybe a better product. It may have been the fact I had any preconceptions about what I had from such a tool. @@ -374,9 +372,9 @@ \subsubsection{Continuous delivery} extremely comforting to know that anything I change is tested and deployed upon commit. Gone is the ``It worked on my machine'' and by using Github to store the project I haven't had to worry about problems like my laptop -breaking losing internet. Fig.~\ref{fig:ghub} are the statistics for this +breaking. Fig.~\ref{fig:ghub} are the statistics for this very report. A release in the report context is a `tag' at a point in the -github history at which a pdf has been produced. +GitHub history at which a pdf has been produced. \begin{figure}[H] \centering @@ -387,9 +385,9 @@ \subsubsection{Continuous delivery} \end{figure} \section{Personal reflections} -On a personal level I have en emense level of proudness surrounding what I +On a personal level, I have an immense level of proudness surrounding what I have delivered. I have become a subject matter expert in producing -accessibile web applications. I have diversified my knowledge in the area of +accessible web applications. I have diversified my knowledge in the area of accessibility. I have experimented with some new ways of working. I have networked with sought after members of the development community and I have taken an idea and delivered it as a product. This project is a great diff --git a/chapters/5-conclusion.tex b/chapters/5-conclusion.tex index c2e8b44..9bf092e 100644 --- a/chapters/5-conclusion.tex +++ b/chapters/5-conclusion.tex @@ -1,7 +1,14 @@ %!TEX root = ../dissertation.tex \chapter{Conclusion} \label{conclusion} +At a high level this project has achieved what it set out to do. A training +guide has been developed and a framework which enables identification of +accessibility issues created. The issues the tool identifies are limited but a +solid example of the `art of the possible' in finding these issues in web +pages is clear. This project has targetted developers which forms only half +the battle. Targetting designers is an area future work should be undertaken +in. -Briefly restate the work done and its outcomes; reflect on what has been -learned from the work and (re)state any consequential recommendations; -(re)acknowledge any limitations and/or give suggestions for further work. +%Briefly restate the work done and its outcomes; reflect on what has been +%learned from the work and (re)state any consequential recommendations; +%(re)acknowledge any limitations and/or give suggestions for further work. diff --git a/references.bib b/references.bib index 5134d80..06d89ea 100644 --- a/references.bib +++ b/references.bib @@ -333,27 +333,17 @@ @misc{jasmine year = {2016}, note = "[Online; accessed 21-May-2017]" } - - - -@article{Eigen1971, - title={Selforganization of matter and the evolution of biological macromolecules}, - author={Eigen, Manfred}, - journal={Naturwissenschaften}, - volume={58}, - number={10}, - pages={465--523}, - year={1971}, - publisher={Springer} +@misc{bookmarklets, + author = {John Udell}, + title = {{Farewell to bookmarks}}, + howpublished = "\url{https://blog.jonudell.net/2015/05/13/farewell-to-bookmarklets/}", + year = {2015}, + note = "[Online; accessed 21-May-2017]" } - -@article{Knuth1968, - title={Semantics of Context-free Languages}, - author={Knuth, Donald E}, - journal={Mathematical Systems Theory}, - volume={2}, - number={2}, - pages={127--145}, - year={1968}, - publisher={Springer} +@misc{chromeapps, + author = {Brian Heater}, + title = {{Google will phase out chrome apps}}, + howpublished = "\url{https://techcrunch.com/2016/08/19/chrome-apps/}", + year = {2016}, + note = "[Online; accessed 21-May-2017]" }