I'm very new to open source, after having spent many years in industry as an embedded systems software/firmware engineer. Over the past couple of days I've been engaged in email conversations with some of my industry colleagues on this topic, so this is a very timely article for me.
How does documentation get generated in hardware-centric high tech? Well yes, there are tech writers who are tasked with writing end-user documentation, and there are project managers, architects, and engineers who are tasked with working with the tech writers to help make sure that the end-user doc is complete and accurate.
But also, as a central part of their job description, project managers, architects, and engineers must generate various types of documentation as part of the design and implementation process. Those docs are the first things turned over to tech writers for use in generating end-user documentation. They also serve to bring the tech writer into the design, implementation, and test process in a very substantive way.
What can be applied to open source? What's the first step? Where's the carrot?
What would motivate an open source project manager to generate a requirements spec, an open source architect to generate design doc, and an open source engineer to generate implementation doc?
1) You’d get higher-quality talent contributing to your project, if you made it easier (faster) for them to get up to speed.
2) You'd have something to hand to a tech writer to get them online sooner.
3) You'd likely end up with a better product, period, if you spent some time documenting stuff like requirements, design, and implementation.
I'm very new to open source, after having spent many years in industry as an embedded systems software/firmware engineer. Over the past couple of days I've been engaged in email conversations with some of my industry colleagues on this topic, so this is a very timely article for me.
How does documentation get generated in hardware-centric high tech? Well yes, there are tech writers who are tasked with writing end-user documentation, and there are project managers, architects, and engineers who are tasked with working with the tech writers to help make sure that the end-user doc is complete and accurate.
But also, as a central part of their job description, project managers, architects, and engineers must generate various types of documentation as part of the design and implementation process. Those docs are the first things turned over to tech writers for use in generating end-user documentation. They also serve to bring the tech writer into the design, implementation, and test process in a very substantive way.
What can be applied to open source? What's the first step? Where's the carrot?
What would motivate an open source project manager to generate a requirements spec, an open source architect to generate design doc, and an open source engineer to generate implementation doc?
1) You’d get higher-quality talent contributing to your project, if you made it easier (faster) for them to get up to speed.
2) You'd have something to hand to a tech writer to get them online sooner.
3) You'd likely end up with a better product, period, if you spent some time documenting stuff like requirements, design, and implementation.