I’ve been thinking about how to get devs to write better docs. It’s always been tough to convince them. Even when they agree it’s important, it rarely happens without a special event.
After learning from some tech writing pros, I wonder if we should treat documentation like we do software design. Maybe we can use the same tools and thinking to make docs better and easier to keep up.
What’s your take? Could this work? Have you found ways to get engineers to write docs? Any tips or methods that have helped?
I’m really curious to hear from other experienced devs on this. It feels like a problem we all face, but maybe there are solutions out there I haven’t thought of yet.
maybe we could use agile methods for docs? like having doc sprints or including doc tasks in our regular sprints. that way it becomes part of the dev process, not an afterthought. also, what about peer reviews for docs like we do for code? might help improve quality and get everyone involved. just brainstorming here!
interesting idea! i’ve struggled with this too. maybe we could use version control for docs like we do for code? that way it’s easier to track changes and collaborate. what about using automated tools to generate some docs from code comments? that could help keep things in sync. have you tried any of these approaches?
Approaching documentation as a software design challenge is an intriguing concept.
From my experience, incorporating documentation into our continuous integration pipeline has been a game-changer. We now treat docs as a first-class citizen alongside our code, which has significantly improved their quality and consistency.
Another effective strategy we’ve implemented is pairing developers with technical writers during sprint planning, ensuring that documentation tasks are prioritized alongside feature development. Additionally, using tools like Swagger for API documentation has helped automate updates based on code changes, keeping our docs current without overburdening our team.