This template was made as a guide to ensure you cover assessment criteria in your second milestone write up. It is specific to the PORTFOLIO 2: Javascript Essentials project. It was based off the loves maths_readmd.md with a few additions to help elevate you to possible distinction status.
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 gitpod workspace
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 ==============================
🚨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
🚨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 JavaScript, 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
🚀 merit & beyond
🚀 merit & beyond
🚀 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 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
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 pdf file in the project itself (in a separate directory), or just hosted elsewhere online and can be in any format that is viewable inside the browser.
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
For some/all of your features, you may choose to reference the specific project files that implement them, although this is entirely optional.
It's easiest to break this section down into the header, footer, and each page/layer 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.
🚀 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 UX 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.
🚨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
styles.css
🚨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.
- You may need a scrolling screenshot to capture this one. I tend to use the GoFullPage extension in chrome:
index.html
404.html
🚨Required
This validator requires you to copy in your code. For each JavaScript file:
- include a screenshot of the JS panel and the right-hand panel that shows now errors.
If you have tons of warnings about spacing and semicolons, right,click your file to format in gitPod and see if that helps. If you have a warning about ES6 or 7 add this to the top of your file:
/*jshint esversion: 6 */
pie.js
🚨Required If you chose to store data in a .json file, you should validate it too.
For each file copy the code into the validator site and include a screenshot
data.json
🚨Required
-
Visit https://gs.statcounter.com/browser-market-share to figure out the most popular browsers & operating system combos seen across the we for the geographic region, and platoform(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. markdown table generator
-
if you can't find the brower/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.
| TOOL / Device | BROWSER | OS | SCREEN WIDTH |
|---|---|---|---|
| real phone: motog6 | chrome | android | XS 360 x 640 |
| browser stack: iPhone5s | safari | iOs | XS 320 x 568 |
| dev tools emulator: pixel 2 | firefox | android | SM 411 x 731 |
| browserstack: iPhone 10x | Chrome | iOs | SM 375 x 812 |
| browserstack: nexus 7 - vert | Chrome | android | M 600 x 960 |
| real tablet: ipad mini - vert | safari | iOs | M 768 x 1024 |
| browserstack: nexus 7 - horiz | firefox | android | LG 960 x 600 |
| chrome emulator: ipad - horiz | safari | iOs | LG 1024 x 768 |
| browserstack | Chrome | windows | XL 1920 x 946 |
| real computer: mac book pro | safari 12.1 | Mohave | XL 1400 x 766 |
| browserstack | IE Edge 88 | windows 10 | XL 1920 x 964 |
🚨Required
For any scenarios that have not been automated, test the user stories manually and provide as much detail as is relevant.
There are 3 ways you can document your testing:
1. Markdown
Describing your testing process is via scenarios, right here such as:
- 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.
2. Use Spreadsheets
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.
3.Use Github Agile Tools
Create Custom Issue Template and A Project Board in git hub.Here's a brief overview I put together on how to do this
It's ok to spot check specific functionality across devices and browsers but each page should be viewed as a whole for each device/browser combo at least once too.
A quick way to check if items are exceeding the screen width of a project is to run this javascript in the console for various screen emulations:
var docWidth = document.documentElement.offsetWidth;
[].forEach.call(document.querySelectorAll('*'),function(el){if(el.offsetWidth > docWidth){console.log(el);}});
🚨Required
Try to create issues in real-time as it better reflects the daily life of a developer.
GitHub has an issues bar that helps you track things pretty quickly. Here's a guide to GitHub Defects
Minimally you could track them as bullet items in this document but the accessors want to know the struggle was real.
🚀 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.
🚨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 https://web.dev/measure/ 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
🚨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.
You should fix issues associated with:
- contrast
- aria labels
- alt text
- large images
- skewed images
Lighthouse https://web.dev/measure/ If you have lower scores, read the report and follow the links to address the flagged issues. 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 in tracking pixel.
You want a score in the green for accessibility and should look at ways to get it to 100.
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 paste it into the readme via GiHu, 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
Once you write javascript, you could use jasmine or jest to automate testing. This stuff isn't covered until you get into the P4 materia! Here's a quick tutorial if you are interested.
🚀 merit & beyond
This section just summarizers tools and programming languages you used.
🚀 merit & beyond
-write bullet points for the languages you used (HTML & CSS)
🚀 merit & beyond
List out the tools you used with a link and a short description (this helps others figure out where to get the bonus points & reminds you what you used for your next project
- Balsamiq
- Coolors.co
- fontawesome
- gitpod
- github
- google fonts
- font awesome
- amiresponsive
- table of contents creator
- markdown table generator
🚨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.
You may want to re-watch the initial deployment in gitpod video when writing up this section.
🚨Required
Write out steps you would take and test them to deploy your code to GitHub Pages, include screenshots if you think they would make the process easier.
🚀 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 :)
🚀 merit & beyond
Enumerate and write the steps of how to run a project locally via gitPod. Include Screenshots to maximize the impact of the instructions.
🚨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.
🚨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.
You should not be using images taken from copyrighted sites, but only royalty free ones. Try typing !copyright in slack and see what help it gives you for this topic.
🚀 merit & beyond
This is the section where you refer to code examples, mentors, blogs, stack overflow answers and videos that helped you accomplish your end project. Even if it's an idea that you updated you should note the site and why it was important to your completed project.
If you used a CodeInstitute Example project as a starting point. Make note of that here.