Disclosure: This article was created or edited with AI assistance. It is educational guidance, not a report of measured results. No measured productivity, hiring, sales or income outcome is claimed. Examples are illustrative unless a source is explicitly given.
The code blocks are educational examples, not a verified production package. Check dependencies, platform compatibility and behavior in your own project.
This is one lightweight way to organize a portfolio. It can complement a site or resume; it does not guarantee a hiring outcome.
File 1: README.md (Your Story)
Not a bio. A narrative.
# Hey, I'm [Name]
I build [type of things] that [solve what problem].
Currently: [what you're working on]
Previously: [most impressive thing you've done]
## What I'm Good At
- [Skill 1]: [proof]
- [Skill 2]: [proof]
- [Skill 3]: [proof]
## What I'm Learning
- [Thing] because [reason]
Why it works: It shows self-awareness and direction.
File 2: PROJECTS.md (Your Proof)
List 3 projects. Not 30. Three.
For each:
- What it does (1 sentence)
- Why you built it (the problem)
- What you learned (the growth)
- Link to live demo or video
File 3: BLOG.md (Your Thinking)
Link to 3-5 technical articles you've written.
This shows you can:
- Communicate complex ideas
- Think beyond just code
- Share knowledge (team player signal)
File 4: CONTRIBUTIONS.md (Your Collaboration)
List open-source contributions, even small ones:
- Bug fixes
- Documentation improvements
- Feature additions
This lets a reader inspect how you contributed to an existing codebase.
File 5: NOW.md (Your Momentum)
Inspired by Derek Sivers' /now page:
- What you're currently building
- What you're learning this month
- What problems you're trying to solve
This gives readers context about what you are currently exploring. Keep the update date visible.
Reasons to consider this format
- It can live alongside your code — link it wherever you share your work
- It is plain text — readers can inspect it without a custom interface
- It's maintainable — update a markdown file vs. redesigning a website
- It shows your actual skills — writing, thinking, building
- It is easy to review — when headings and links are clear
Include only work and outcomes you can substantiate. Private work can be described within confidentiality limits; an empty public contribution graph does not establish a lack of experience.
Top comments (0)