Comments on: The Catch-22 Of Opensource Documenation http://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/ Living in a state of accord. Wed, 03 Dec 2008 01:40:31 +0000 http://wordpress.org/?v=2.6.5 By: Adrian Sutton http://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82339 Adrian Sutton Mon, 28 May 2007 09:04:49 +0000 https://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82339 Rick, Yeah someone pointed that out on the last post. It gives a good architectural overview but unfortunately it's not a reference which is what I desperately need right now. Rick,
Yeah someone pointed that out on the last post. It gives a good architectural overview but unfortunately it’s not a reference which is what I desperately need right now.

]]> By: Rick Evans http://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82335 Rick Evans Mon, 28 May 2007 08:28:24 +0000 https://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82335 Hi Adrian I daresay you already know about this resource, but for those readers of your blog that might not, InfoQ has a new book devoted to Struts2. http://www.infoq.com/minibooks/starting-struts2 I take your point about paid-for-docco though, cheers Rick Hi Adrian

I daresay you already know about this resource, but for those readers of your blog that might not, InfoQ has a new book devoted to Struts2.

http://www.infoq.com/minibooks/starting-struts2

I take your point about paid-for-docco though, cheers
Rick

]]> By: Adrian Sutton http://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82172 Adrian Sutton Sun, 27 May 2007 21:15:33 +0000 https://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82172 Rick, Struts 2 is the main source of frustration for me, but the other project that kicked me over to this rant was hibernate. Not so much that it's documentation is completely useless, but instead of the website pointing you to the docs, it recommends you go and buy an e-book instead. Hopefully there is good documentation in there somewhere but it was just another data point of docs being a paid extra instead of the enabling feature that makes the code useful. Rick,
Struts 2 is the main source of frustration for me, but the other project that kicked me over to this rant was hibernate. Not so much that it’s documentation is completely useless, but instead of the website pointing you to the docs, it recommends you go and buy an e-book instead. Hopefully there is good documentation in there somewhere but it was just another data point of docs being a paid extra instead of the enabling feature that makes the code useful.

]]> By: Rick Evans http://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82169 Rick Evans Sun, 27 May 2007 20:45:36 +0000 https://www.symphonious.net/2007/05/27/the-catch-22-of-opensource-documenation/#comment-82169 Hi Adrian Well go on then, name 'em and shame 'em I say (the OS projects that have rubbish documentation, or have just paid-for documentation available). I seem to remember a developer on one OS project posting something along the lines of 'users of OSS have *no* right to expect anything [such as documentation].' The attitude seemed to be one of 'caveat emptor', which seems to me to be the wrong attitude to take, but that's one of the realities of OSS. I'm actually struggling to think of an OS project (one that I use regularly) that doesn't have adequate documentation... I say 'adequate', because the software is 'free', so I don't go in expecting 100% polished, uber-comprehensive documentation. As a developer on an OS project I can say that writing the documentation is not a task that brings one a lot of glory (any glory actually - in fact, one often gets ribbed for taking some time out to write some documentation), so it's no wonder that it comes low in the priority list of things to do in an evening after one's paid day job. One important part of documentation that you didn't mention was forums... yeah, not strictly documentation, but if the forums are lively enough they can be an excellent resource, full of tips and stuff that ain't in the main documentation for one reason or another (space, focus, etc.). Over time they do become a documentation resource (of sorts), and (speaking personally) whenever I see something cool on the Spring forums that deserves to be in the Spring documentation, I go off and add it. I'll enter into the spirit of naming and shaming to start you off, and rip into the Spring documentation :) I don't think the Spring documentation is too bad (I am trying to be unbiased); however, it does suffer from not being very well organised, there are no tutorials per se, and there are to date no hardcopy books devoted to coverage of Spring 2... basically, as it stands right now, if it ain't in the Spring documentation then it ain't anywhere. As to what is being done to remedy this, as regards the Spring documentation, I'm aware of it's shortcomings (mmm, not much else happening there though), and there are other folks out there who are writing Spring 2.0+ books (Craig Walls for example). http://www.manning.com/walls3/ I'd be interested to hear what OS projects folks rate as having rank, Stoke, Trent, and otherwise rubbish docco :) Cheers Rick Hi Adrian

Well go on then, name ‘em and shame ‘em I say (the OS projects that have rubbish documentation, or have just paid-for documentation available).

I seem to remember a developer on one OS project posting something along the lines of ‘users of OSS have *no* right to expect anything [such as documentation].’ The attitude seemed to be one of ‘caveat emptor’, which seems to me to be the wrong attitude to take, but that’s one of the realities of OSS. I’m actually struggling to think of an OS project (one that I use regularly) that doesn’t have adequate documentation… I say ‘adequate’, because the software is ‘free’, so I don’t go in expecting 100% polished, uber-comprehensive documentation. As a developer on an OS project I can say that writing the documentation is not a task that brings one a lot of glory (any glory actually - in fact, one often gets ribbed for taking some time out to write some documentation), so it’s no wonder that it comes low in the priority list of things to do in an evening after one’s paid day job.

One important part of documentation that you didn’t mention was forums… yeah, not strictly documentation, but if the forums are lively enough they can be an excellent resource, full of tips and stuff that ain’t in the main documentation for one reason or another (space, focus, etc.). Over time they do become a documentation resource (of sorts), and (speaking personally) whenever I see something cool on the Spring forums that deserves to be in the Spring documentation, I go off and add it.

I’ll enter into the spirit of naming and shaming to start you off, and rip into the Spring documentation :)

I don’t think the Spring documentation is too bad (I am trying to be unbiased); however, it does suffer from not being very well organised, there are no tutorials per se, and there are to date no hardcopy books devoted to coverage of Spring 2… basically, as it stands right now, if it ain’t in the Spring documentation then it ain’t anywhere. As to what is being done to remedy this, as regards the Spring documentation, I’m aware of it’s shortcomings (mmm, not much else happening there though), and there are other folks out there who are writing Spring 2.0+ books (Craig Walls for example).

http://www.manning.com/walls3/

I’d be interested to hear what OS projects folks rate as having rank, Stoke, Trent, and otherwise rubbish docco :)

Cheers
Rick

]]>