<story><title>WTFM - Write The Freaking Manual</title><url>http://www.floopsy.com/post/32453280184/w-t-f-m-write-the-freaking-manual</url></story><parent_chain><item><author>exDM69</author><text>When it comes to open source work, which I mostly do on my own, limited time and don&apos;t get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don&apos;t like at all. Guess which I am going to pick.&lt;p&gt;The times when I&apos;ve actually ended up writing some docs, I don&apos;t think anyone has ever read them. And writing the docs is just the beginning, they have to be maintained too. Out of date docs are perhaps worse than no docs at all.&lt;p&gt;I don&apos;t read docs either, because they tend to be out of date. Formal specifications are an exception. But when it comes to open source, I just tend to read the source because it&apos;s never out of date and tells the whole story. What was obvious to writer of the doc isn&apos;t obvious to me and vice versa.&lt;p&gt;The first person who comes to me asking for documentation to my projects volunteers to write them, like it or not.</text></item></parent_chain><comment><author>nathan_long</author><text>&amp;#62; I can spend time writing code or writing documentation.&lt;p&gt;You are selling yourself short. Your documentation the first thing people see. If it says &quot;incomplete, confusing, and half-hearted&quot;, I&apos;m going to hit the back button in about 15 seconds. I&apos;m not going to spend 15 minutes reading your code to see if the first impression is wrong unless I think there&apos;s no viable alternative project.&lt;p&gt;Conversely, if your documentation is clear, thorough, and gives examples of usage, I&apos;m likely to trust your project and dig deeper.&lt;p&gt;It&apos;s even been argued that writing the docs first helps you develop better: &lt;a href=&quot;http://tom.preston-werner.com/2010/08/23/readme-driven-development.html&quot; rel=&quot;nofollow&quot;&gt;http://tom.preston-werner.com/2010/08/23/readme-driven-devel...&lt;/a&gt;</text></comment>
<story><title>WTFM - Write The Freaking Manual</title><url>http://www.floopsy.com/post/32453280184/w-t-f-m-write-the-freaking-manual</url></story><parent_chain><item><author>exDM69</author><text>When it comes to open source work, which I mostly do on my own, limited time and don&apos;t get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don&apos;t like at all. Guess which I am going to pick.&lt;p&gt;The times when I&apos;ve actually ended up writing some docs, I don&apos;t think anyone has ever read them. And writing the docs is just the beginning, they have to be maintained too. Out of date docs are perhaps worse than no docs at all.&lt;p&gt;I don&apos;t read docs either, because they tend to be out of date. Formal specifications are an exception. But when it comes to open source, I just tend to read the source because it&apos;s never out of date and tells the whole story. What was obvious to writer of the doc isn&apos;t obvious to me and vice versa.&lt;p&gt;The first person who comes to me asking for documentation to my projects volunteers to write them, like it or not.</text></item></parent_chain><comment><author>xradionut</author><text>I&apos;ve wasted hundreds of hours dealing with piss-poor or no documentation, reading/debugging code, searching sites and forums just to find the magical combo of steps that get a application to build correctly or an LED to blink.&lt;p&gt;I don&apos;t have unlimited time to figure out your code, API and lack of documents. I would rather deal with OSS or commercial software that respects me.</text></comment>