One or two paragraphs providing an overview of your project. Tell us what your project is about and what it does. Keep it under 250 words.
If your README is long, add a table of contents to make it easy for users to find what they need. To create a table of contents, use the markdown toc generator: https://ecotrust-canada.github.io/markdown-toc/
Here you want to breakdown your projects design objectives and decisions. I warmly recommend using the five planes of UX design to help you with this. You can find more information about the five planes here: https://www.interaction-design.org/literature/topics/ux-design-the-five-planes-of-user-experience
This involves identifying the objectives of the website from both user and business perspectives. You should also consider the needs of the users and the business, and any constraints that may impact the project.
Question to ask yourself:
- What are you aiming to achieve with this project?
- What is the main goal? (e.g. sell a product, raise awareness for a cause, etc.)
- What are the goals of your users?
- Build a website that is easy to navigate and use.
- Build a website that is responsive on all devices.
- Build a website that is accessible to all users.
- Build a website that is visually appealing.
- Build a website that is interactive.
- Build a website that is informative.
- Build a website that is secure.
- Build a website that is fast.
- Build a website that is scalable.
- Build a website that is maintainable.
- Build a website that is extensible.
- Build a website that is testable.
- Build a website that is reusable.
- Build a website that is readable.
- Build a website that is portable.
- Build a website that is compatible.
- Build a website that is consistent.
- Build a website that is predictable.
- Build a website that is flexible.
- Build a website that is stable.
- Build a website that is fault tolerant.
- Build a website that is recoverable.
- Build a website that is secure.
- Build a website that is robust.
- Build a website that is usable.
- ...
- User Goals:
- User Goal 1
- User Goal 2
- ...
- Business Goals:
- Business Goal 1
- Business Goal 2
- ...
After defining the objectives, determine the features and content necessary to meet those goals. This involves listing functionalities in order of priority, and identifying the content that will be needed for the site.
Question to ask yourself:
- What features do you want to include in your design?
- What's on the table?
- What's off the table?
- What are the limitations?
- What are the constraints?
- What are the assumptions?
- What are the dependencies?
- What are the risks?
- What are the considerations?
- What are the principles?
- What are the priorities?
- What are the requirements?
- What are the deliverables?
- What are the milestones?
- What are the tasks?
- What are the deadlines?
- What are the costs?
- What are the resources?
- ...
What makes your project stand out? Go over its unique features here, different parts of your project and what they do. A sentence or two for each. Explain what these features do and why they are beneficial for the user. Focus on who your audience is and highlight the benefits for them. How your project is going to help them?
Existing Features:
- Feature 1 - allows users X to achieve Y, by having them fill out Z
- ...
Features Left to Implement
- Feature 2 - Feature idea 2
- ...
Content
Content is the information provided on your site and can include text, images, videos, audio, etc. This may be directly related to the product or service you are offering, or simply provide information to the audience on the subject of your site.
- Content 1 - https://www.example.com
- Content 2 - https://www.example.com
- etc...
This involves organizing the information and functionality into groups, and determining how these groups relate to each other. This step can be illustrated using a sitemap or user flow diagram. This includes the information architecture, menu structure, and pathways users will take to access different sections or pages.
Question to ask yourself:
- How is the information structured?
- How is the information logically grouped?
- How is the information categorized?
- How is the information organized?
- How is the information prioritized?
- How is the information sequenced?
- How is the information labeled?
- How is the information formatted?
- How is the information presented?
- How is the information accessed?
- How is the information navigated?
- How is the information searched?
- How is the information filtered?
- How is the information validated?
- How is the information secured?
- How is the information stored?
- How is the information retrieved?
- How is the information updated?
- How is the information deleted?
- How is the information archived?
- How is the information backed up?
- How is the information restored?
- How is the information shared?
- How is the information protected?
- ...
-
Navigation:
- Navigation 1
- Navigation 2
- ...
-
Pathways/:
- Pathway 1
- Pathway 2
- ...
This involves creating a low-fidelity wireframe to outline the basic structure of the site, and a high-fidelity wireframe to show the final appearance of the site. This step can be illustrated using a wireframe or mockup.
-
Layout:
- Layout 1
- Layout 2
- ...
-
Elements:
- Element 1
- Element 2
- ...
This involves determining the mood and tone of the site. This step can be illustrated using a mood board or style tiles.
-
Visual Design:
- Visual Design 1
- Visual Design 2
- ...
-
Typography:
- Typography 1
- Typography 2
- ...
-
Imagery:
- Imagery 1
- Imagery 2
- ...
Describe the process of testing the code you've written. If you have a separate testing repository, link to it here.
- HTML
- CSS
- JavaScript
- Python
- etc...
- User Story 1
- User Story 2
- ...
- Describe any prerequisites, libraries, OS version, etc., needed before installing program.
- ex. Windows 10
- How/where to download your program
- Any modifications needed to be made to files/folders
- etc...
- How to run the program
- Step-by-step bullets
code blocks for commands
Add additional notes about how to deploy this on a live system. Include screenshots and code examples if necessary.
Any advise for common problems or issues.
Contributors names and contact info
Inspiration, code snippets, etc.
- Content 1 - https://www.example.com
- Content 2 - https://www.example.com
- etc...
- Media 1 - https://unsplash.com/photos/some-photo
- Media 2 - https://unsplash.com/photos/some-photo
- etc...
Here you should mention the tech stack used to create your project. For more aesthetic READMEs, you can use skill-icons to generate a list of icons for your tech stack.
- Technology 1 - version 1.0
- Technology 2 - version 2.0
- etc...