The Decision to Build A Portfolio On A Documentation Framework

When thinking deeply about the construction of the average portfolio, a question often arises in my mind: how can someone build a portfolio that grows alongside their skills without distracting from the learning process itself? Designing a visually appealing portfolio is certainly a skill of its own, but I also believe in the importance of putting pen to paper. A good portfolio is meant to impress – yet without strong fundamentals, it all falls apart.

Over the years, I’ve tasked myself with building portfolios using different frameworks in an effort to learn something new each time. With the endless possibilities and constantly evolving technologies, it often felt like I was always chasing the new exciting tool that companies were looking for. In doing so, I always felt that I was unable to truly develop my skillset. While familiar with many technologies is not inherently a bad thing, I now believe in strong fundamentals and building from there. Through this reflection, I’ve landed on an interesting proposition. To build a portfolio on a framework focused on documentation creation.

Documentation frameworks are built to communicate information quickly and clearly. Recruiters, hiring managers, and collaborators don’t want to hunt for details, so there’s real value in presenting key points in a layout that makes sense at a glance. Unlike the typical flashy portfolio filled with animations, Nextra emphasizes the documentation experience by combining the flexibility of Next.js with the simplicity of Markdown. This gives me the freedom to build custom React components while still being able to deploy updates through straightforward Markdown files.

A portfolio should also never be static — just like how our projects, experiences, and skills, it should evolve over time. With Nextra, I can add new sections, publish blog posts, or expand on case studies without having to redesign the entire site. As developers, our portfolios should reflect both our work and the tools we might use in production. By building with Nextra I’m able to demonstrate a familiarity with React, Next.js, Markdown, and even documentation workflows while also being able to demonstrate the value of documentation and organization. Beyond that, my portfolio also serves as a live sandbox where I can experiment with ideas and share personal projects in real time. “Knowledge without application is merely knowledge. True learning comes from application.”

While I believe Nextra offers clarity and structure, this is not to say it does not come with some potential pitfalls. Its minimal design can feel too plain or impersonal without extra branding, resulting in a portfolio that may fail to convey personality and be deemed as underwhelming. In a non-technical environment, this type of portfolio might seem less visually engaging than the traditional design-focused sites. To this, I’d like to argue that through careful execution of styling and react components, this type of site can quickly become more personal. Learning how to quickly and effectively implement this may even be fun!

So what do we learn here? A portfolio doesn’t have to chase every new trend to be effective. By focusing on clarity, structure, and fundamentals of good documentation, we create a space that evolves with our skills, communicates our abilities clearly, and still allows for creativity. Ultimately it’s about balancing form and function — building something that’s both professional and personal, while staying true to the work we do.