Documentation That Does Not Sit on a Shelf - An Introduction to Real Documentation

Making Documentation Real with Interactive Prototyping Tools

Welcome to our new Bug Driven Developers this week! If you enjoy this post, forward it to your developer friends so they can join us.

Here’s what we got for you today:

  • Creative ways to extend the lifespan of your documentation with Real Documentation

  • Use AI to remove backgrounds

  • Startup founder with zero customers

📄 Let's start off this week by talking about documentation

Developers create documentation to share ideas with team members, serve as a reference for their future selves, meet compliance requirements, and for countless other reasons. Yet, it often feels like documentation is the appendix of software development: it's there, but nobody really knows what it's for. Sure, management emphasizes its importance, and you read about "best practices" online, but do your team members truly read and comprehend the documentation you create? Or do they just skim through it to get the gist?

Enter what we are coining "Real Documentation" – a dynamic alternative to traditional text-based software documentation. By leveraging the many tools available today, you can create mock prototypes in the same amount of time it takes to write a conventional document. In the following sections, we'll explore how Real Documentation can revolutionize the way you communicate your software designs and ideas, making your documentation more engaging and effective.

👨‍💻 Real Documentation for UI/UX Design

In the past, UI/UX designs were created by specialized designers using tools like Adobe Suite. They would gather ideas, craft beautiful screens, and share them with the team and stakeholders for feedback. While UI/UX design remains a form of art, modern tools like Figma have made it easier for anyone to turn their ideas into interactive mockups and click-through demos even before writing a single line of code.

These interactive demos are far more effective for gathering feedback from users, team members, and stakeholders compared to static Adobe designs in PowerPoint or PDFs. They also surpass traditional text-based documents describing features, their appearance, and positioning. Real Documentation is all about showing, not telling, when it comes to presenting your UI/UX designs. By embracing click-through demos, you can significantly enhance communication and collaboration within your team.

🕸️ Real Documentation for APIs and Microservices

API specifications serve more purposes than merely outlining request and response formats. They can also be used to generate mock servers, empowering fellow developers to experiment with APIs before their actual implementation. Instead of solely relying on an OpenAPI Specification or a Postman Collection, consider creating a mock server in Postman that includes all API endpoints with sample data resembling real API responses.

This approach is beneficial for both adding or revising an API in an existing service and creating a brand-new microservice. The mock server enables developers to test APIs by consuming them as they would with the completed version, which in turn helps them provide more actionable feedback on improving the API or service design. By adopting Real Documentation in this context, you can enhance collaboration and streamline the API development process.

🐾 Next Steps for Real Documentation

Real Documentation offers a fresh perspective on how we approach software development documentation. By shifting our focus from traditional text-based documents to interactive, hands-on prototypes and mock servers, we can bridge the communication gap between developers, stakeholders, and users. This approach not only streamlines the development process but also facilitates better feedback and understanding among team members.

Embracing tools like Figma for UI/UX design and Postman for API mock servers allows for a more dynamic and immersive documentation experience. As the software development landscape continues to evolve, it's crucial to adopt practices that keep pace with modern demands. Real Documentation is an innovative approach that enables us to create more effective and engaging documentation, ultimately leading to better products and improved collaboration.

It's time to leave those dusty, unread documents behind and embrace the future of documentation. With Real Documentation, we can transform the way we communicate our ideas and ensure that our work doesn't just sit on a virtual shelf but plays an active role in the development process.

As we continue to explore the potential of Real Documentation, stay tuned for more guides and insights in future Bug Driven Development blog posts. We're excited to share the journey with you, as we collectively redefine the role of documentation in software development.

🔗Links in Tech

Some additional reads we liked this week

😂 Meme of the Week

🤖 Update is launching soon! See a more detailed update on Justin’s personal website here:

Thanks for tuning in to this week’s newsletter! If you have any questions, feel free to let us know on Twitter (Justin's Twitter) (Kevin's Twitter)


Justin + Kevin

P.S. What new things about Software Development did you learn this week?

Did you enjoy reading this week's Bug Driven Development?

Join the conversation

or to participate.