Real World Guidelines
Table of Contents
Real World Guidelines
Structured template of table of contents for GitHub Documentation
Table of Contents
Project Title
Project Description
Table of Contents
Project Overview
Project Description
Project Goals
Key Features
Getting Started
Prerequisites
Setup Instructions
Installation
Features
Examples
Technical Requirements
Hardware Requirements
Software Requirements
Network Requirements
Technical Details
Architecture
Project Structure
Packages (If used)
Security (If used)
Security Overview
Security Best Practices
Wiki
Wiki Overview
Contributing
Contributing Guidelines
Code of Conduct
License and Copyright
License
Attribution
Contact and Support
Contact Information
About Developer
Support Resources
FAQs
Glossary
Documentation
Breakdown Table of Contents
#Project Title
##Project Description
Brief summary 1-2 sentences
***
##Table of Contents
***
##Project Overview
***
###Project Description
More detailed explanation of project 2-3 paragraphs
###Project Goals
List project goals
###Key Features
Key Features of the project
##Getting Started
***
###Prerequisites
List necessary prerequisites for using project, what you need to get started
###Setup Instructions
List setup configuration requirements to use project
###Installation
Step-by-step instructions for installing project
##Features
***
List project features, include notable functions, integration, or tools
(Use this section to highlight project capabilities and benefits)
###Examples
Include examples or use cases to illustrate project functionality
##Technical Requirements
***
(Use this section to help readers understand project, technical dependencies, and limitations)
###Hardware Requirements
List hardware requirements (RAM, CPU, etc)
###Software Requirements
List software requirements (Visual Studio Code, libraries, etc)
###Network Requirements
List network requirements (internet connectivity, etc)
##Technical Details
***
###Architecture
Describe project architecture (Visuals- Diagrams, design process)
###Project Structure
List and describe file structure of project
###Packages (If used)
List and describe packages used in the project
##Security (If used)
***
###Security Overview
Describe overview of project’s security features and considerations
###Security Best Practices
List and describe best security practices for using the project
##Wiki
***
###Wiki Overview
Brief overview of wiki and purpose
##Contributing
***
###Contributing Guidelines
Describe guidelines for contributing to the project (how to join the project)
###Code of Conduct
Describe code of conduct for people who want to join
##License and Copyright
***
###License
Specify project’s license and any relevant copyright information
###Attribution
Explain any credit or acknowledgments (third-parties libraries, frameworks, etc) used in the project. Explain any sources or inspirations (research, code, borrowed or adapted) used in the project
##Contact and Support
***
###Contact Information
Provide contact information (email, supporting channels-youtube)
####About Developer
Short bio of me (something not from my resume, GitHub profile)
###Support Resources
####FAQs
List question and answers (general questions about project- information that is not explained in README)
####Glossary
List key terms or concepts used in the project
####Documentation
List and describe sources used (explain the why I went that route)
Structured template of wiki for GitHub Documentation
Wiki Home Page
Wiki Title
Wiki Overview
Table of Contents
Introduction
Tutorials
Title of tutorial
Tutorial instruction steps
Methodologies
Name of methodology
Overview
Benefits
Challenges
Approaches
Name of approach
Overview
Benefits
Challenges
Resources
Name of resource
Link (name)
Description
Glossary
References
FAQs
Breakdown Wiki Home Page
####Wiki Title
##Wiki Overview
Brief overview of wiki’s purpose 1-2 sentences
***
##Table of Contents
##Introduction
***
More detailed explanation of wiki’s purpose 1-2 paragraphs
##Tutorials
***
###Title of tutorial
Name of the tutorial
(explain purpose of tutorial- reason for having it, why is it important)
###Tutorial instruction steps
Detailed instructions (step 1, 2, etc)
##Methodologies
***
###Name of methodology
Name of methodology
####Overview
Detailed explanation of methodology (include explanation of the why it’s being used)
####Benefits
List benefits of using methodology
####Challenges
List any challenges experienced with methodology
##Approaches
***
###Name of approach
Name of approach
####Overview
Detailed explanation of approach (include explanation of the why it’s being used)
####Benefits
List benefits of using approach
####Challenges
List any challenges experienced with approach
##Resources
***
###Name of resource
Name of resource
####Link
Link to the resource
####Description
Explanation of the resource (why it was used)
###Glossary
List key terms or concepts used in the project
###References
Explain any sources used in wiki
##FAQs
***
List question and answers (general questions about wiki- information that is not explained in wiki
Structured real-world guidelines for any project
Personal Project Guidelines
Project Initialization
Define project goals or objectives
Clearly explain what you want to achieve by building the project (it’s purpose)
Conduct feasibility assessment (need to create)
Assess resources, time, and skills to do the project
Create a project plan
Create a plain (milestones and deadlines)
Setup repository
Create project repository GitHub
Code Management
Use version control system
Use a version control system, Git
Follow a coding standard (need to create coding standard)
Establish coding standard (ensure consistency and readability across code base)
Code base = foundation of software, includes all files needed to compile the software
Write clean and modular code
Reusable modules to improve maintainability and scalability
Modular code = Breaking code into smaller separate pieces that do one specific thing. If one part needs fixing or changed, work on specific notes: part without breaking entire code
Use a code editor or IDE
Choose correct editor or IDE for project
Code editor = write and edit code, simple (Ex: notepad)
IDE (Integrated Development Environment) = all-in-one solution, writing, testing, and managing code
Testing and Debugging
Write unit tests
Create unit tests (ensure code quality and catch errors)
Use a testing framework (create testing framework template based on language)
Use testing framework like Playwright (other options- Selenium, Jest, Pytest, Unittest, etc)
Use a debugger (create debugger based on language)
Use a debugger like Chrome DevTools (other options- Node.js Inspector, Angular Augury, SonarLint, etc)
Code Review and Refactoring
Regularly review code (figure out when to stop building and start review)
Schedule review of code to ensure code quality and identify areas for improvement
Refactor code
Refactor to improve maintainability, scalability, and performance
Refactor code = clean up or improve the structure of the code without changing what the code does (Ex: Make code simpler to read, remove duplicate code, break big pieces into smaller and reusable parts)
Use code analysis tools (create and figure out when to use analysis tools)
Use code analysis tools (never use any- Code Factor, Code Climate, PMD, etc)
Keep code organized
Keep code organized (comments, documentation, and formatting)
Security and Best Practices
Follow security best practices (need to create security practice)
Implement security practices, secure coding practices, secure data storage, and secure authentication
Use security tools
Use security tools (never used any- Zap, Bearer, Horusec, etc) to identify and address security
Keep dependencies up-to-date
Do regular updates on dependencies (ensure latest security patches and features)
Dependencies = External tools or libraries in project (extra features)
Documentation
Write documentation
Create documentation (comments, README)
Keep project journal
Track progress, lessons learned, plan future improvements
Use documentation templates (need to create)
Ensure consistency across projects
Project Completion
Define project completion criteria (need to create)
Create clear criteria for project completion (what constitutes a completed project)
Create project completion checklist (need to create)
Create checklist to ensure all tasks are completed before completed
Conduct final project review
Perform review of project, met requirements of completion
Document lessons learned
Document lessons learned during project (improve future project outcomes)
Step-by-step Personal Project Guidelines
Project: purpose, what you are building
Project Goal: short explanation of project, purpose for building, “it’s the why are you building”
Project Objectives: explain, what you want to achieve with the project
Step 1: Project Initialization
Define project goals and objectives
Review project goals and objectives (can it be improved from brainstorming, more detailed, tailored focused)
(write down project goals and objectives in project plan document)
Conduct feasibility study
Research existing applications of what you are building (identify features, and functionality)
Determine technical feasibility of project (do you know the programming language for the project (if not, time to learn) framework, and tools)
Identify potential roadblocks and challenges (learning curve, any problem you can think of)
Create project plan
Breakdown project into smaller tasks and milestones
Create a project timeline with est. completing dates
Identify dependencies and (API, library, etc) critical path tasks (create tests at review checkpoints)
Setup project repository
Create repository, GitHub (README, gitignore) (start basics for version control, documentation)
Step 2: Development
Code management
Use coding standard and follow throughout project (start version control, even if its small)
Create frontend
Design wireframe (outline, mindmap, etc) and user interface
Use framework to start building UI (basic from wireframe “improve over time of project”)
Create backend
Setup backend language (API, Node.js, Python, etc)
Create authentication and authorization
Setup library for authentication Supabase (Passport, etc)
Setup library for authorization Supabase (Casbin, Remult, etc) or role-based access control (Casbin, OpenFGA, etc)
Authentication = Proving who you are (Ex: logging into email)
Authorization = Deciding what you're allowed to do (Ex: After logging into your email, decides if you can read, send, or delete emails.)
Step 3: Testing and Debugging
Write unit tests
Use testing framework like Playwright (other options- Selenium, Jest, Pytest, Unittest, etc)
Test individual components and functions
Write integration tests
Use testing framework (FitNesse, Citrus, etc) to test application’s functionality and user interface
Debug code
Use a debugger to identify and fix issues (don’t forget console logs and print statements to debug code)
Step 4: Security and Best Practices
Follow security best practices
Use HTTPS and SSL/TLS to encrypt data
Secure password storage library like bcrypt
Secure authentication and authorization
Use security tools
Use a tools like ZAP identify vulnerabilities
Use SSL Checker test SSL/TLS configuration
Keep dependencies up-to-date
Use npm or pip to manage dependencies
Regularly update dependencies to ensure you have the latest security patches
Step 5: Documentation
Write documentation
Create a README explains how to use the application
Write documentation (API, frontend, back, etc)
Use documentation templates
Use a template like Slite (The Good Docs Project) to create documentation and GitHub to host
Step 6: Project Completion
Define project completion criteria
Determine what constitutes a completed project
Create a checklist of tasks to complete
Conduct a final project review
Review project to ensure it meets the goals and objectives
Identify areas for improvement and create a plan to address them
Document lessons learned
Write a post document summarizes the project
Identify lessons learned and areas for improvement
Last updated