This template was made as a guide to ensure you cover assessment criteria in your first write up. It is specific to the USER CENTRIC FRONTEND MILESTONE project.
Sections marked as 🚨Required and 🚀 merit & beyond
Please note that project assessment criteria changes more often than these guides are updated so double-check the submission criteria before assuming the 🚨Required is all you have to do to pass.
Here’s a great video on how to add videos to your readme! no need to convert to gifs!!
https://www.youtube.com/watch?v=G3Cytlicv8Y
- record a video via slack
- download it
- in github, edit your readme via the pencil icon
- type a place holder word and highlight it
- drag and drop mp4 file over that text
- scroll down to the commit area
- update the default commit message
- click the green button
git pullchanges to your IDE workspace to avoid conflicts
You can do the steps 3-9 for the image/screenshot uploads too!
Markdown's not all that easy so sometimes you may want to use some tools to make tables.
- Markdown Cheatsheet
- markdown table generator - used to help with documentation table formatting
- mardown table of contents generator - used to create table of contents (be weary it does have some bugs if you have dashes or trailing spaces in your headers)
- readme.so - if you don't want to learn markdown, this tool might help you
Copy your readme to http://ecotrust-canada.github.io/markdown-toc/ to make a table of contents. This will help assessors to see the structure of your readme. Just test it out ast this tool isn't perfect. It tends to mess up with special characters like dashes.
====================================== The Sections you Fill in are below with some instructions ==============================
🚨Required
replace the PROJECT NAME header with your project's name
- One or two paragraphs providing an overview of your project.
- Write this as a sales pitch or commercial to entice users to interact with your site or how you want investors to purchase your website.
- Include a picture of site that shows it in responsive states and links to deployed code: https://ui.dev/amiresponsive
DEVELOPER_NAME
- Include a picture of site that shows it in responsive states and links to deployed code: http://ami.responsivedesign.is/
- One or two paragraphs providing an overview of your project.
- Write this as a sales pitch or commercial making users want to purchase your website.
- Include a link to your deployed website
🚨Required
- Include a link to deployed project (typically a GitHub Page on github.io)
🚨Required
- Include a Link to the GitHub repository
🚨Required
DEVELOPER_NAME (take credit for the work you do!)
🚀 merit & beyond
Generate after readme is complete by copying and pasting your readme from this point & below into this tool:
- mardown table of contents generator NOTE: It does have some bugs if you have dashes or trailing spaces in your headers
🚀 merit & beyond
This particular section can be blank, it's just a wrapper for the child sections.
The subsections provide insight into your UX process, focusing on why you made the user experience decisions you did. If the target audience and user base drove you to a certain look and feel call it out so the accessors can't be objective and say I don't like it.
🚀 merit & beyond
Your site is most likely geared to a certain audience, and your design choices should tie into them, pay attention to age groups, genders, demographics, & interests of the people you are hoping to use your site. If it's everyone, say so.
🚀 merit & beyond
Write bullet points of what this site is trying to achieve.
- This site presents X to Y with specific features.
- Another completely valid project goal is building your skill set with a focus on HTML and CSS :)
🚀 merit & beyond
This section lists outs as a X I want Y, so I can Z format. It helps drive out the features you will build.
You can have many kinds of users so feel free to have one section or the subsections listed or more
🚀 merit & beyond
These stories are focused on the users of the site, they can be focused around specfic controls and roles, but you should definitely have things like the following in there too:
Ex)
- As a customer on the site I want to have navigation that sticks with me as a I scroll so it's easy to go to the parts of the site I'm interested in.
- As a customer I want to have use an intuitive website so I don't get frustrated when finding information I'm looking for on a website.
🚀 merit & beyond
These user stories are based on the site owner, they want to earn money or provide information and avoid lawsuits. So write user stories from that perspective.
Ex)
- As a site owner, I want to make sure my site meets web accessiblity guidelines around colors and contrast so I can provide a good online experience to all users, even those with visual impairments.
- As a site owner, I want a fully responsive website so I can provide information about my company to people no matter what device they use to visit my site.
🚀 merit & beyond
These stories are typically from your standpoint, if you want show you are profcient in a language, or have skills to show off.
- As a develeper, I want to produce a stunning protfolio project so that my future employers know I create quality web sites.
🚀 merit & beyond
Your site is most likely geared to a certain audience, and your design choices should tie into them. Let the assessors know your thought process.
You may want to re-watch the videos about the 5 planes of UX development when writing up this section
🚀 merit & beyond
- Discuss your color pallet choices and how it ties into users' emotions or target audience.
- include a screenshot of your pallet using a tool like coolors.co
🚀 merit & beyond
- discuss font size, font types for headers vs buttons vs general text and how it ties into users' emotions or target audience.
- Clarity of letters, putting a capital i next to a lower case L is always a good test
- include screenshots of fonts used and links to the appropriate website ex) https://fonts.google.com/specimen/Raleway
🚀 merit & beyond
Explain why you used certain icons and images on your site & tie it back into your target audience
🚀 merit & beyond
- discuss any special animations or transitions you've included
- special hover state effects
🚀 merit & beyond
Talk about if the site is 1 page vs multiple pages. Say what loads by default & how to get access to other pages/sections.
🚀 merit & beyond
what are some of they key User Interactive elements and bits of functionally you will have on your site: tables, accordions, maps, videos, forms with inputs, text areas, select/dropdowns
🚀 merit & beyond
This section is also where you would share links to any wireframes, mockups, diagrams etc. that you created as part of the design process. These files should themselves either be included as a separate .md file, or open a pdf file in the project itself or screenshots in line.
Wireframes can be as simple as a picture of a drawing of how you envisioned laying out the information for you pages in desktop, tablet and mobile views. They are a roadmap and do not have to be 100% accurate of the final product. Or you can use the Balsamiq tool that Code Institute provides students access to.
🚀 merit & beyond
🚀 merit & beyond
🚀 merit & beyond
🚨Required
In this section, you should go over the different parts of your project, and describe each in a sentence or so and how they tie into your user stories.
🚨Required
It's easiest to break this section down into the header, footer, and each page/layer/signification section of your website. Call out any differences for mobile vs desktop presentations, include a screenshot of the implemented feature.
Don't forget your 404 error page.
For some/all of your features, you may choose to reference the specific project files that implement them, although this is entirely optional.
🚀 merit & beyond
Use this section to discuss plans for additional features to be implemented in the future
If you end up not developing some features you hoped to implement, you can include those in this section too.
🚨Required
In this section, you need to convince the assessor that you have conducted enough testing to legitimately believe that the site works well. Essentially, in this part you will want to go over all of your user stories from the Features section and ensure that they all work as intended, with the project providing an easy and straightforward way for the users to achieve their goals.
If this section grows too long, you may want to split it off into a separate file and link to it from here.
🚨Required
In this section you should write up any websites you used to validate your code and include screenshots.
Validation issues are an automatic failure You should run these about 3 times:
-
when you first deploy your site
-
just when you think you are done testing
-
right before you submit because 😼, ⚽, 🐶 & 👼 can eliminate a closing tag or curly bracket without you noticing.
-
You may need a scrolling screenshot to capture the valitaion outputs. I tend to use the GoFullPage extension in chrome:
🚨Required
If you only have one CSS file used on all pages, you only need to run this once for your deployed url, but if you have different files for different pages, run it by direct input per file.
- include a screenshot for each CSS file which includes the Green no ERRORS bar, two check marks
🚨Required
If you only have one HTML file for your project, you only need to run this once for your deployed url, but if you have different files even for a thankyou or 404, run it by direct input per file or by deployed url per file.
-
include a screenshot for each HTML file with the Blue Nu Html checker down to the blue checking complete bit. It's ok to have info and warnings.
Blue to blue
Note any errors or warnings you are ignorning and why. IT IS BEST NOT to have ERRORS, but COLOR VARIABLES sometimes are ok to ignore if you say the IDE that has the correct linters noted no errors. Or you can take the rendered HTML and run it through the HTML validator for the Flask html templates.
Ideally you would bullet point your each of your HTML files and add a screenshot of the validation tool's output proving all was good.
🚨Required
Minimally you should use dev tools and emulators to try to test you site on various screen sizes and browsers and note it in a table:
I ensured my site was worked well, and looked nice on a variety of devices & browsers as noted in the table below:
| TOOL / Device | BROWSER | OS | SCREEN WIDTH |
|---|---|---|---|
| real phone: motog6 | chrome 78 | android 8 | XS 360 x 640 |
| browser stack: iPhone5s | safari 13 | iOs | XS 320 x 568 |
| dev tools emulator: pixel 2 | firefox 69 | android 8 | SM 411 x 731 |
| browserstack: iPhone 10x | Chrome 78 | iOs 11 | SM 375 x 812 |
| browserstack: nexus 7 - vert | Chrome 78 | android 7 | M 600 x 960 |
| real tablet: ipad mini - vert | safari 13 | iOs 6 | M 768 x 1024 |
| browserstack: nexus 7 - horiz | firefox 69 | android 7 | LG 960 x 600 |
| chrome emulator: ipad - horiz | safari 13 | iOs | LG 1024 x 768 |
| browserstack windows PC | Chrome 78 | windows 10 | XL 1920 x 946 |
| real computer: mac book pro | safari 12.1 | Mohave | XL 1400 x 766 |
| browserstack windows pc | IE Edge 88 | windows 10 | XL 1920 x 964 |
🚀 merit & beyond Document why you chose the devices:
-
Visit https://gs.statcounter.com/browser-market-share to figure out the most popular browsers & operating system combos seen across the web for the geographic region, and platform(s) and screen sizes you expect your users to belong to.
-
Include a sentence about why you chose the combinations you did.
-
Create a table that lists out what devices, browsers, and operating system you tested your application on and a brief description of why you chose the mixture you did. The point is to prove that you looked at the site across various browsers, operating systems, and viewport breakpoints.
-
if you can't find the browser/device/OS combinations you want on Browserstack with your GitHub student webpack (or you didn't activate that in time), note what you'd ideally test on then what you ended up testing on as a compromise.
-
Build a table to summarize the choices you made markdown table generator
The combinations above were chosen because of the following information I gathered from ga.statcounter.com for the US from Aug-Oct 2021: browser Version Market Share:
- safari iphone: 26.32%
- chrome for android: 21.32%
- Chrome 105.0: 15.77%
- Chrome 104.0: 6.28%
- Edge 105: 4.99%
- Safari 15.6 3.76% browser Market Share
- chrome: 50.28%
- Safari: 34.65%
- Edge: 6.37%
- Firefox: 3.52%
- Samsung Internet: 2.04%
- Opera: 0.89% platform breakdown
- mobile: 51.26%
- desktop: 45.73%
- tablet: 2.97%
- console: 0.03%
🚨Required
For any scenarios that have not been automated, test the user stories/features manually and provide as much detail as is relevant. A particularly useful form for describing your testing process is via scenarios in markdown such as:
Manual Testing For Contact Form
- Contact form:
- Go to the "Contact Us" page
- Try to submit the empty form and verify that an error message about the required fields appears
- Try to submit the form with an invalid email address and verify that a relevant error message appears
- Try to submit the form with all inputs valid and verify that a success message appears.
Or you can use markdown check boxes and write them up per feature:
Manual Testing For Contact Form
- try to submit
- Try to submit the empty form and verify that an error message about the required fields appears
- Try to submit the form with an invalid email address and verify that a relevant error message appears
- Try to submit the form with all inputs valid and verify that a success message appears.
- no console errors
- submit goes to code institute data dump page in new tab
- looks good on mobile (one column)
- looks good on tablet (two columns)
- looks good on desktop (two columns but not SUPER HUGE)
Or you can use a spreadsheet
Here is a Manual Testing Template that you can use as a starting point to keep track of your testing efforts. Make a copy of it in your own account and update as needed to reflect the browsers you are testing and features.
Make sure on smaller devices to check for horizontal scrolling.
A quick way to check if items are exceeding the screen width of a project is to temporarilly add this CSS to your file and review the site to see if any red lines to to the left:
* {outline: 1px solid red;}
🚨Required
Try to create issues in real time as it better reflects the daily life of a developer.
The easiest way to track defects is by using GITHUB's Issues to track these as it's really easy to copy/paste screenshots in and then write up how you closed them. At this stage you don't need a custom template or labels, that comes in later projects.
Here's a quick overview of creating GitHub issues
You can also just bullet point them here, or create a google spreadsheet and link to that here.
🚀 merit & beyond
Some defects are more pesky than others. Highlight 3-5 of the bugs that drove you the most nuts and link to them directly here. The accessors really like to know the struggle is real and that by doing this you picked up more skills.
🚨Required
It's ok to not resolve all the defects you found as long as:
- it does not impact a user from completing a vital function on the website
- it only affects a very small subset of users
- is an extreme edge case that very few users would try
- there is an open issue against a framework, browser or technology used
If you know of something that isn't quite right, create an issue and link to it here and explain why you chose not to resolve it.
Sometimes it's as simple, word wrapping issue that makes the site look odd at a certain screensize that you just didn't have time to fix due to the impending deadline it's best to mention it but note why you allowed it to go live: "Yes it looks odd, but it doesn't impact core functionality of the site." than to let the accessors think you didn't notice it.
🚀 merit & beyond SEO is greatly impacted by your core web vitals. The readout from Page Speed Insights which is essentially a lighthouse audit gives your site scores in 4 categories. Ideally you want your site to be in the green for all 4 scores. web.dev has dedicated servers to test deployed sites without extensions that skew the results, so it's best to get results from this site.
You should talk about the results for each section pay attention to anything brought up in the accessiblity section.
🚨Required
Accessibility testing is aimed to make sure that those with visual or physical disabilities can still browse your website. Some users have had strokes or accidents that make it difficult to use a mouse, so they use keyboard keys to tab through sites. Others use screen readers that rely on HTML tags to help the user navigate quickly through the site to find information they want, others have color blindness or contrast issues. It's the law to provide services Here's a site where you can learn more about accessibility and the internet.
🚨Required
Accessibility audits run through the HTML and determine if the parts of the WCAG (web content accessibility guidelines ) that are implemented through HTML tags and attributes are present. They can do some checking for low vision/contrast stuff too.
You should run your deployed website pages through at least on auditing tool. lighthouse's audit to check performance, accessibility, best practices and SEO scores. You should aim to get 85 or higher score on accessibility.
Lighthouse You can run this tool from Chrome Dev Tools too against your local machine, but chrome extensions can sometimes give you missing alt text on things like the grammarly plug or other tracking pixels. Page Speed Insights does the same audits as the lighthouse devtools option, but on dedicated servers without plug ins that might give you false positives.
Pay attention to the Accesiblity score. If your score is not 100, click on the circle and read the report and follow the links to address the flagged issues.
You want a score in the green for accessibility and should look at ways to get it to 100.
You should fix issues associated with:
- contrast
- aria labels
- alt text
- large images
- skewed images
Provide a screenshot of each .html's file lighthouse audit score for both mobile and desktop as proof of your testing
WAVE chrome extension Wave is developed by webaim.org and does a bit better at contrast issues and uses 2.1 guidelines
Contrast Checkers
🚀 merit & beyond
Another way to accessibility test your site is to try to click on the browser URL and see what happens if you use the tab, arrow and enter keys. Does it work well or does the user get stuck? Check this in a couple browsers as the focus & active outlines are typically styled by the browser
The expected results for various keyboard entries and field types can be found here
You can take a video of this testing if you want and convert it to a gif and paste that into your readme. Record something to yourself in a Slack direct message, then download it. Then you can use https://cloudconvert.com/mp4-to-gif to convert the mp4 to a gif and just drag and drop it into the readme via editing it in GitHub, and it'll resolve itself.
🚀 merit & beyond
If you are really ambitious, you can use the VoxReader extension in chrome to see what your site sounds like on a screen reader. It really drives home the need for good aria-labels & semantic HTML.
🚀 merit & beyond
In this section, you should mention the languages, frameworks, libraries, and any other tools that you have used to construct this project. For each, provide its name, a link to its official site and a short sentence of why it was used.
-
If you included a js file that isn't your own, add it here.
-
If you included a css file that isn't your own, add it here.
-
Common 3rd party technologies to list:
- wirefames
- favicons
- color palette images
- fonts
- CSS Frameworks
- markdown tables
- markdown table of contents
Please note, if this gets more than 5 items, you may want to break it down into logical subsections
- JQuery The project uses JQuery to simplify DOM manipulation.
- CSS The project uses CSS to define DOM appearance.
- HTML The project uses HTML to define DOM elements.
- Markdown Documentation within the readme was generated using markdown
- Bootstrap 4.0 Rather than re-invent many things, I chose to customize the look and feel of bootstrap 4.0
- google sheets & drive - Used to create testing documents and project plan (feature to do list)
- FontAwesome - for icons associated with buttons and inputs
- Patrick Hand SC - Google Font's Patrick Hand font was used for headers and home page dialog
- Raleway - Google's Raleway font was used as the main font
- github - used for version control of project files and branching out to try different things without adversely affecting a functional set of code
- balsamiq - used to create professional looking wire frames.
- markdown table generator - used to help with documentation table formatting
- mardown table of contents generator - used to create table of contents (be weary it does have some bugs if you have dashes or trailing spaces in your headers)
- colors.co I used a colors.co's color pallet tool to help pick complementary colors.
- SMTP - Send emails to users
- Google Maps Javascript API - Customized Mapping Widgets
OPTIONAL If you have trouble with being able to check in your code, add this section and explain why your commits are so few, or why your commit messages were bad in the beginning. You need to let the accessors know why you didn't follow best practices, but you are aware of those best practices are.
🚨Required
This section should describe the process you went through to deploy the project to a hosting platform (e.g. GitHub Pages).
In particular, you should provide all details of the differences between the deployed version and the development version, if any.
Remember to use proper markdown for commands and enumerated steps.
🚀 merit & beyond
A fork creates a completely independent copy of Git repository. In contrast to a fork, a Git clone creates a linked copy that will continue to synchronize with the target repository, so if you want to ensure other people don't commit to your public repo, you might want to tell them to fork the repository :) Forking Doc
🚀 merit & beyond
Write out the steps you take starting from cloning the repository in github or clicking a gitpod button to run your code locally. Test it out and make sure it works. This can be running from your IDE of choice like VSCode or PyCharm, CodeAnywhere, or GitPod. (Add screenshots to steps to make it really easy for a newbie to know what to do )
You may want to re-watch the initial deployment videos when writing up this section.
🚨Required
Write out steps you would take and test them to deploy your code to GitHub Pages. (Add screenshots to steps to make it really easy for a newbie to know what to do )
🚨Required
To avoid plagiarism amd copyright infringement, you should mention any other projects, stackoverflow, videos, blogs, etc that you used to gather imagery or ideas for your code even if you used it as a starting point and modified things. Giving credit to other people's efforts and ideas that saved you time acknowledges the hard work others did.
(Include the lessons or templates from CI and this guide if you copy some stuff from it. )
🚨Required
Use bullet points to list out sites you copied text from and cross-reference where those show up on your site
🚨Required
Make a list of sites you used images from. If you used several sites try to match up each image to the correct site. This includes attribution for icons if they came from font awesome or other sites, give them credit.
🚀 merit & beyond
This is the section where you refer to code examples, mentors, blogs, friends, tutors, co-workers who helped you accomplish this mighty feat of a quality first website.
If you used a CodeInstitute Example project as a starting point. Make note of that here too just to be safe.