One of the essential draws to open-source software should be superior product documentation. Well-written user guidelines are a key strategy that software developers should use to increase an open-source project’s growth and user adoption.
Colleagues,
I currently work as a freelance Technical and Business writer. I could not agree more with your analysis of the "Documentation Dearth." Please tell me how I might join in and contribute to YOUR efforts to create good documentation for open source (FLOSS) projects.
I have some observations and insight from my own efforts and career. I worked as a software developer for over 30 years until "retirement." Where might I direct my writings on this topic for your review? I find that too many folks completely dismiss postings and other writings about documentation. Your recent "Dearth" article contains many of the reasons why this is the case. There are other reasons.
~~~ 0;-Dan
Most Open Source projects do not have any systematic way for WRITERS to ask questions and get answers about the software. Frequently, a WRITER must resort to black-box testing [little or no access to the application internals] techniques hoping to discover what the software does. This explains why so much of what claims to be documentation is little more than an inventory of forms and fields and buttons and menus. These get padded with screen capture images and wrapped in prose that says, "... I poked it and this is what happened ..."
Of course it is useful when the programmers embed descriptive information into the code itself. It is even more helpful when there are tools to extract and format this information for easy consumption. However, I experienced embedded information that is most useful to other programmers and only marginally useful to an end-user. For real, end-user value, one needs a WRITER first and foremost. I trained to be such a WRITER.
I worked over 30 years designing and writing code and documentation to support it. WRITERS most often cannot (or do not want to) read code to discover detailed information about software. They must have access to subject matter experts.
I can read the code and other developer materials and I have tried without success to contribute documentation into several projects in the Linux(tm) ecosystem. Code reading takes huge amounts of time to have confidence that one understands what one is reading. It often requires more time and effort investedd in tool chains along with project and developer workflow.
A primary difficulty lies with the lack of access to experts for detailed questions and honest dialog. Just as "programmers" see those who write device drivers as a breed apart, so too must Open Source project embrace WRITERS as another different breed with their own needs supporting successful documentation.
I am ready and willing to contribute my prose to projects who support their WRITIERS with access to information and folks who can and will answer questions under some reasonable project process.
Loading ...
Dan Allen and Sarah White: Documentation Dearth Dooms Open Source Projects
Posted by: Jack M. Germain September 24, 2014 06:04 PMOne of the essential draws to open-source software should be superior product documentation. Well-written user guidelines are a key strategy that software developers should use to increase an open-source project’s growth and user adoption.
I currently work as a freelance Technical and Business writer. I could not agree more with your analysis of the "Documentation Dearth." Please tell me how I might join in and contribute to YOUR efforts to create good documentation for open source (FLOSS) projects.
I have some observations and insight from my own efforts and career. I worked as a software developer for over 30 years until "retirement." Where might I direct my writings on this topic for your review? I find that too many folks completely dismiss postings and other writings about documentation. Your recent "Dearth" article contains many of the reasons why this is the case. There are other reasons.
~~~ 0;-Dan
Of course it is useful when the programmers embed descriptive information into the code itself. It is even more helpful when there are tools to extract and format this information for easy consumption. However, I experienced embedded information that is most useful to other programmers and only marginally useful to an end-user. For real, end-user value, one needs a WRITER first and foremost. I trained to be such a WRITER.
I worked over 30 years designing and writing code and documentation to support it. WRITERS most often cannot (or do not want to) read code to discover detailed information about software. They must have access to subject matter experts.
I can read the code and other developer materials and I have tried without success to contribute documentation into several projects in the Linux(tm) ecosystem. Code reading takes huge amounts of time to have confidence that one understands what one is reading. It often requires more time and effort investedd in tool chains along with project and developer workflow.
A primary difficulty lies with the lack of access to experts for detailed questions and honest dialog. Just as "programmers" see those who write device drivers as a breed apart, so too must Open Source project embrace WRITERS as another different breed with their own needs supporting successful documentation.
I am ready and willing to contribute my prose to projects who support their WRITIERS with access to information and folks who can and will answer questions under some reasonable project process.