.comment-link {margin-left:.6em;}
Sunday, April 18, 2010

Socratic and Verbalization: Documenting on both sides 
Francisco Tolmasky gave a talk at #jsconf on Socratic: Documentation Done Right. He asked for feedback and he got me thinking about the problem that coders documentation does not even help them when they go back to it. Ever have that happen with your documentation? Go back to your source comments three months later and they don't make much sense?

The process of coding involves variable and method names which are suppose to be meaningful. A convention has evolved where methods should be verbs because they do something and variables are nouns. Roughly.

So I suggested to Francisco that perhaps Socratic could use Verbalization to verify that methods are verbs. Think of Verbalization as a spell check of only verbs. Maybe it could check that "is" methods are boolean and perhaps more. I suppose the Nounization could be done on variables.

One theme at JSCONF is running JavaScript on client and the server. For example, same validation method on both. This got me thinking about the documentation divide. So why not run Verbalization on both Socratic and Textmate or your IDE. As you build out your code check that your method names are verbs. And this gets you a glossary? So a common plug system for both Socratic and IDEs would be good.

Just a thought or two with a lot more to think about.


permalink ( Sunday, April 18, 2010 ) Ray 0 comments links to this post

Comments: Post a Comment

Links to this post:

Create a Link

Daly blog unless thee forget.

Presentation Blogs
Sudoku Games and Tools for Beginner or Obsessed
JavaScript HTML Editor (1996)
Multipurpose Room Blog
Design and Innovation
Create enewsletters with RSS and JS
Bucknell Blogging Friends
David Winberger
Richard Herring
Pete Murchison
Blog Reading
Dave Winer
Art of Getting Over
DC Blogs:
Site Feed - Atom

March 2003
July 2003
August 2003
September 2003
October 2003
November 2003
December 2003
January 2004
February 2004
March 2004
April 2004
May 2004
June 2004
July 2004
August 2004
September 2004
October 2004
November 2004
December 2004
January 2005
February 2005
March 2005
April 2005
May 2005
June 2005
July 2005
August 2005
September 2005
October 2005
November 2005
December 2005
January 2006
February 2006
March 2006
April 2006
May 2006
June 2006
July 2006
August 2006
September 2006
October 2006
November 2006
December 2006
January 2007
February 2007
March 2007
April 2007
June 2007
July 2007
August 2007
September 2007
October 2007
December 2007
March 2008
April 2008
May 2008
June 2008
August 2008
November 2008
December 2008
May 2009
June 2009
August 2009
September 2009
December 2009
January 2010
March 2010
April 2010
Powered by Blogger