open source docs: the good, the bad, and the wtf?!
DESCRIPTION
Open source documentation is generally awful, often frightening, and sometimes it’s just outright weird. In this discussion, I will show you examples from the entire spectrum of open source documentation, in an effort to try and help you avoid some of the worst mistakes made by others before you. We will discuss why documentation is important for open source projects, and how to go about getting it written, and written well, without making too much of a fool out of yourself.TRANSCRIPT
Open Source DocumentationOpen Source Documentation
The good The bad
And the WTFWTF ?!?!
I'm all in favor of keeping
dangerous weapons out of the
hands of fools.
Let's start with typewriters.
Unprovided with original learning, unformed in the habits of thinking,
unskilled in the arts of composition,
I resolved to write a book.
In certain kinds of writing ... it is normal to come
across long passages which are almost
completely lacking in meaning.
CloudForms, which is based upon the company-sponsored CloudForms, which is based upon the company-sponsored DeltaCloud project that is now part of Apache– offer DeltaCloud project that is now part of Apache– offer
sophisticated resource management, application deployment sophisticated resource management, application deployment services and Infrastructure-as a Service offerings that help IT services and Infrastructure-as a Service offerings that help IT
adminstrators implement private and hybrid clouds.adminstrators implement private and hybrid clouds.
The platform consists of a cloud engine for high level The platform consists of a cloud engine for high level automation and abstraction services across multiple automation and abstraction services across multiple
virtualization hypervisors and virtualized clusters, an virtualization hypervisors and virtualized clusters, an application engine and system engine for comprehensive application engine and system engine for comprehensive application lifecycle management across multiple cloud application lifecycle management across multiple cloud
providers and various Infrastucture -as-a-Service offerings providers and various Infrastucture -as-a-Service offerings including storage, messaging and high availability services.including storage, messaging and high availability services.
http://www.zdnet.com/blog/open-source/red-hat-launches-cloudforms-iaas-openshift-paas-platforms/8803http://www.zdnet.com/blog/open-source/red-hat-launches-cloudforms-iaas-openshift-paas-platforms/8803
CloudForms, which is based upon the company-sponsored CloudForms, which is based upon the company-sponsored DeltaCloud project that is now part of Apache– offer DeltaCloud project that is now part of Apache– offer
sophisticated resource management, application deployment sophisticated resource management, application deployment services and services and Infrastructure-as a ServiceInfrastructure-as a Service offerings that help IT offerings that help IT
adminstratorsadminstrators implement private and hybrid clouds. implement private and hybrid clouds.
The platform consists of a cloud engine for high level The platform consists of a cloud engine for high level automation and abstraction services across multiple automation and abstraction services across multiple
virtualization hypervisors and virtualized clusters, an virtualization hypervisors and virtualized clusters, an application engine and system engine for comprehensive application engine and system engine for comprehensive application lifecycle management across multiple cloud application lifecycle management across multiple cloud
providers and various providers and various InfrastuctureInfrastucture -as-a-Service offerings -as-a-Service offerings including storage, messaging and high availability services.including storage, messaging and high availability services.
http://www.zdnet.com/blog/open-source/red-hat-launches-cloudforms-iaas-openshift-paas-platforms/8803http://www.zdnet.com/blog/open-source/red-hat-launches-cloudforms-iaas-openshift-paas-platforms/8803
Typos are very important to all written form.
It gives the reader something to look for
so they aren't distracted by the
total lack of content in your writing.
Advice to writers: Sometimes you just have to stop writing.
Even before you begin.
