Comments on: Wikis **Are** For Documentation http://paul-m-jones.com/archives/153?utm_source=rss&utm_medium=rss&utm_campaign=wikis-are-for-documentation It's not enough to be smart; you have to actually know things. Wed, 16 May 2012 17:27:27 +0000 hourly 1 http://wordpress.org/?v=3.1 By: the ryan king » Content first, structure later http://paul-m-jones.com/archives/153/comment-page-1#comment-352241 the ryan king » Content first, structure later Wed, 14 May 2008 00:00:07 +0000 http://paul-m-jones.com/blog/?p=153#comment-352241 [...] M. Jones has a great blog post entitled Wikis **Are** For Documentation. He says: This stand [that wikis are insufficient for documentation -ed.], in my opinion, [...] [...] M. Jones has a great blog post entitled Wikis **Are** For Documentation. He says: This stand [that wikis are insufficient for documentation -ed.], in my opinion, [...]

]]> By: pmjones http://paul-m-jones.com/archives/153/comment-page-1#comment-79742 pmjones Thu, 26 Oct 2006 19:22:17 +0000 http://paul-m-jones.com/blog/?p=153#comment-79742 The Midgard guys noted this blog entry some time ago: <a href="http://article.gmane.org/gmane.comp.web.midgard.devel/5485" rel="nofollow">http://article.gmane.org/gmane.comp.web.midgard.devel/5485</a> The Midgard guys noted this blog entry some time ago:

http://article.gmane.org/gmane.comp.web.midgard.devel/5485

]]> By: the ryan king » Blog Archive » Content first, structure later http://paul-m-jones.com/archives/153/comment-page-1#comment-15232 the ryan king » Blog Archive » Content first, structure later Fri, 29 Jul 2005 17:58:44 +0000 http://paul-m-jones.com/blog/?p=153#comment-15232 [...] Paul M. Jones has a great blog post entitled Wikis **Are** For Documentation. He says: This stand [that wikis are insufficient for documentation -ed.], in my opinion, addresses the wrong problem. My basic rebuttal would be that PHP userland lacks not merely “robust” documentation, but that it lacks “almost all” documentation. The key here is not merely to improve the state of existing docs, but to get **any** docs to exist in the first place … and wikis help with this tremendously. They are not perfect, but they are a great start to get some docs out there. [...] [...] Paul M. Jones has a great blog post entitled Wikis **Are** For Documentation. He says: This stand [that wikis are insufficient for documentation -ed.], in my opinion, addresses the wrong problem. My basic rebuttal would be that PHP userland lacks not merely “robust” documentation, but that it lacks “almost all” documentation. The key here is not merely to improve the state of existing docs, but to get **any** docs to exist in the first place … and wikis help with this tremendously. They are not perfect, but they are a great start to get some docs out there. [...]

]]> By: Paul M. Jones http://paul-m-jones.com/archives/153/comment-page-1#comment-10771 Paul M. Jones Thu, 16 Jun 2005 19:13:40 +0000 http://paul-m-jones.com/blog/?p=153#comment-10771 All -- agreed that API docs require a great deal of structure. However, that is completely automated via processing of doc-blocks in the code itself, and mostly useless except as a reference when you already know the class moderately well. End-user docs are my target here. As far as inter-page linking, Text_Wiki handles it very nicely. In fact, on the Solar wiki pages, I've set it up so that interwikis use double-colons, not just single-colors. With that one change, every time you type ClassName::methodName(), it converts to a link to the ClassName area and the methodName() page. Same for ClassName::$property. Makes it really easy to link pages. All — agreed that API docs require a great deal of structure. However, that is completely automated via processing of doc-blocks in the code itself, and mostly useless except as a reference when you already know the class moderately well. End-user docs are my target here.

As far as inter-page linking, Text_Wiki handles it very nicely. In fact, on the Solar wiki pages, I’ve set it up so that interwikis use double-colons, not just single-colors. With that one change, every time you type ClassName::methodName(), it converts to a link to the ClassName area and the methodName() page. Same for ClassName::$property. Makes it really easy to link pages.

]]> By: Matthew Weier O'Phinney http://paul-m-jones.com/archives/153/comment-page-1#comment-10762 Matthew Weier O'Phinney Thu, 16 Jun 2005 18:55:14 +0000 http://paul-m-jones.com/blog/?p=153#comment-10762 Lukas -- re: API vs. end user docs. I absolutely agree, and made that the point of my own blog entry (referenced in an earlier comment). I feel that this is what Paul is getting at as well. The API docs *should* and *will* remain structured, as they will be auto-generated from phpdoc blocks. But end user documentation is the part that has the highest barrier to entry, as this is where DocBook comes into play. And when it comes down to it, end user docs often need even less structure than the API docs -- some simple headings, some lists, some paragraphs. Sean has made some fine points -- inter-page linking is harder to maintain on docs that are distributed. But I feel that Text_Wiki actually has the ability to handle that already, and could likely export documents in such a way that these issues would be overcome. Lukas — re: API vs. end user docs. I absolutely agree, and made that the point of my own blog entry (referenced in an earlier comment). I feel that this is what Paul is getting at as well. The API docs *should* and *will* remain structured, as they will be auto-generated from phpdoc blocks. But end user documentation is the part that has the highest barrier to entry, as this is where DocBook comes into play.

And when it comes down to it, end user docs often need even less structure than the API docs — some simple headings, some lists, some paragraphs.

Sean has made some fine points — inter-page linking is harder to maintain on docs that are distributed. But I feel that Text_Wiki actually has the ability to handle that already, and could likely export documents in such a way that these issues would be overcome.

]]> By: Lukas http://paul-m-jones.com/archives/153/comment-page-1#comment-10622 Lukas Wed, 15 Jun 2005 21:30:32 +0000 http://paul-m-jones.com/blog/?p=153#comment-10622 one more thing: i agree that you want structure for API docs, but end user docs dont need structure quite as badly. one more thing: i agree that you want structure for API docs, but end user docs dont need structure quite as badly.

]]> By: Lukas http://paul-m-jones.com/archives/153/comment-page-1#comment-10621 Lukas Wed, 15 Jun 2005 21:29:43 +0000 http://paul-m-jones.com/blog/?p=153#comment-10621 "Imagine reading a newspaper that used a random font and text size in each article?" Wikis dont allow all that much different markup to really make this a valid comparision. “Imagine reading a newspaper that used a random font and text size in each article?”

Wikis dont allow all that much different markup to really make this a valid comparision.

]]> By: Sean Coates http://paul-m-jones.com/archives/153/comment-page-1#comment-10613 Sean Coates Wed, 15 Jun 2005 17:53:17 +0000 http://paul-m-jones.com/blog/?p=153#comment-10613 Short response... You make some good points. I definitely agree with you on the 'PEAR needs good docs, PERIOD, even if they're not docbook' point. I don't, however agree with the "docs don't need to be semantic and structured" point. Imagine reading a newspaper that used a random font and text size in each article? Imagine if the pages were numbered non-sequencially (but no worries: there's an index at the back)? We can agree to disagree on this, if you like, but I strongly assert that the best documentation (and I truly believe that phpdoc is some of the best open source documentation available) IS semantic, robust and structured. There's a value to changing formats. Livedocs (once working properly with all php.net doc projects) will solve the accessibility problems. As it stands, I can change phpdoc (and as long as I don't add entities (including files), or change the master manual file), I can see the changes, rendered, instantly in Livedocs. If I _DO_ change entities/manual master, it's a matter of seconds (sometimes minutes) to re-`build.sh`, and not hours (as it stands with the DSSSL build). My only other point: my biggest fear of a wiki for PEAR packages is not that people will use it as a base for their docs, but that it will _become_ the docs due to laziness and negligence (they'll never get ported to the "official" format). The docs, while somewhat useful, will remain mediocre. If you're going to do something: do it well. MHO. (oh.. and too bad you didn't trackback me (rather, your trackbacks don't seem to work properly).. I'd have seen this sooner (-: ) S Short response…

You make some good points. I definitely agree with you on the ‘PEAR needs good docs, PERIOD, even if they’re not docbook’ point.

I don’t, however agree with the “docs don’t need to be semantic and structured” point. Imagine reading a newspaper that used a random font and text size in each article? Imagine if the pages were numbered non-sequencially (but no worries: there’s an index at the back)? We can agree to disagree on this, if you like, but I strongly assert that the best documentation (and I truly believe that phpdoc is some of the best open source documentation available) IS semantic, robust and structured. There’s a value to changing formats.

Livedocs (once working properly with all php.net doc projects) will solve the accessibility problems. As it stands, I can change phpdoc (and as long as I don’t add entities (including files), or change the master manual file), I can see the changes, rendered, instantly in Livedocs. If I _DO_ change entities/manual master, it’s a matter of seconds (sometimes minutes) to re-`build.sh`, and not hours (as it stands with the DSSSL build).

My only other point: my biggest fear of a wiki for PEAR packages is not that people will use it as a base for their docs, but that it will _become_ the docs due to laziness and negligence (they’ll never get ported to the “official” format). The docs, while somewhat useful, will remain mediocre. If you’re going to do something: do it well. MHO.

(oh.. and too bad you didn’t trackback me (rather, your trackbacks don’t seem to work properly).. I’d have seen this sooner (-: )

S

]]> By: Lukas http://paul-m-jones.com/archives/153/comment-page-1#comment-10548 Lukas Wed, 15 Jun 2005 08:52:37 +0000 http://paul-m-jones.com/blog/?p=153#comment-10548 Does this post mean its time that I bring up my feature requests on the yawiki list again? ;-) Does this post mean its time that I bring up my feature requests on the yawiki list again? ;-)

]]> By: Matthew Weier O'Phinney http://paul-m-jones.com/archives/153/comment-page-1#comment-10515 Matthew Weier O'Phinney Wed, 15 Jun 2005 03:36:22 +0000 http://paul-m-jones.com/blog/?p=153#comment-10515 Tried using the trackback, but it didn't work. I've posted a response to this at: http://weierophinney.net/matthew/archives/79-PHP-Application-Documentation.html Tried using the trackback, but it didn’t work. I’ve posted a response to this at:

http://weierophinney.net/matthew/archives/79-PHP-Application-Documentation.html

]]>