SQL Server JDBC - JDBC Driver API Documentation in Javadocs?

Author

JDBC Driver API Documentation in Javadocs?

Acey Bunch

2006-02-07, 8:23 pm

Hi Folks,

For version 1.0 of the JDBC driver, we made the decision to forgo the
Javadocs format in favor of having a more integrated help system formatted
as flat HTML files. However, we have received some feedback that Javadocs
would be the preferred format.

We'd like to hear from more of you on this issue, please let us know what
you think of the current format of the API documentation.

Thanks...

Acey Bunch
Lead Programmer Writer
Microsoft JDBC Driver Team

Tharon LeBlanc

2006-02-08, 9:23 am

html is fine, however javadocs is the standard. why not go with that if it
is an option. all (most) java devs will be familiar with it.

Thanks.

"Acey Bunch" <aceyb@microsoft.com> wrote in message
news:OHmPkvCLGHA.3264@TK2MSFTNGP11.phx.gbl...
> Hi Folks,
>
> For version 1.0 of the JDBC driver, we made the decision to forgo the
> Javadocs format in favor of having a more integrated help system formatted
> as flat HTML files. However, we have received some feedback that Javadocs
> would be the preferred format.
>
> We'd like to hear from more of you on this issue, please let us know what
> you think of the current format of the API documentation.
>
> Thanks...
>
> Acey Bunch
> Lead Programmer Writer
> Microsoft JDBC Driver Team
>

Jason Viers

2006-02-08, 9:23 am

Acey Bunch wrote:
> For version 1.0 of the JDBC driver, we made the decision to forgo the
> Javadocs format in favor of having a more integrated help system formatted
> as flat HTML files.

"more integrated" into what? What advantages do flat HTML files give
over Javadoc HTML files?

The advantage of Javadoc files is we know exactly what to expect. I
like glancing at Javadoc and knowing exactly where to look for what, as
the format's always the same.

Unless there's some super-duper awesome reason to use flat HTML files,
I'd say it'd be best to stick to the Java world's standard.

just my 2 cents
Jason

Angel Saenz-Badillos[MS]

2006-02-09, 1:23 pm

I believe (and I am sure he will correct me if I am wrong) that Acey meant
more integrated into msdn:
http://msdn2.microsoft.com/en-us/library/ms378749.aspx

We NEED to ship in a format that can fit into msdn, what we are wondering if
it is worth to do the work to make it _also_ fit in the javadoc format. This
would be a time consuming task (we would not want to maintain two separate
doc branches so traditional documenting at the source code level is not
feasible) and it will affect the quality of the v1.1 docs since we have
limited manpower to go arround.

Given these parameters we are looking for feedback on specific scenarios,
things like "I am used to press f1 on editor xxx to get my documentation" ,
so that we can make an educated decision going forward.

Thanks,

--
Angel Saenz-Badillos [MS] DataWorks
This posting is provided "AS IS", with no warranties, and confers no
rights.Please do not send email directly to this alias.
This alias is for newsgroup purposes only.
I am now blogging: http://weblogs.asp.net/angelsb/

"Jason Viers" <bean@beanalby.net> wrote in message
news:e0eQZDMLGHA.500@TK2MSFTNGP15.phx.gbl...
> Acey Bunch wrote:
>
> "more integrated" into what? What advantages do flat HTML files give over
> Javadoc HTML files?
>
> The advantage of Javadoc files is we know exactly what to expect. I like
> glancing at Javadoc and knowing exactly where to look for what, as the
> format's always the same.
>
> Unless there's some super-duper awesome reason to use flat HTML files, I'd
> say it'd be best to stick to the Java world's standard.
>
> just my 2 cents
> Jason

Acey Bunch [MSFT]

2006-02-14, 8:23 pm

Actually, by integrated I am mainly referring to having the conceptual and
API content in one help system, with many links between them. That is, as
you read a conceptual topic you'll get links into related API topics.

Angel's summary of what we are looking for is correct. We're wrestling with
the issue of whether or not to also ship the API content in a Javadoc
format, which as he points out, means maintaining two doc branches, which we
of course want to avoid.

Thanks for the comments...

-Acey

"Angel Saenz-Badillos[MS]" <angelsa@online.microsoft.com> wrote in message
news:OsYl4waLGHA.2828@TK2MSFTNGP12.phx.gbl...
>I believe (and I am sure he will correct me if I am wrong) that Acey meant
>more integrated into msdn:
> http://msdn2.microsoft.com/en-us/library/ms378749.aspx
>
> We NEED to ship in a format that can fit into msdn, what we are wondering
> if it is worth to do the work to make it _also_ fit in the javadoc format.
> This would be a time consuming task (we would not want to maintain two
> separate doc branches so traditional documenting at the source code level
> is not feasible) and it will affect the quality of the v1.1 docs since we
> have limited manpower to go arround.
>
> Given these parameters we are looking for feedback on specific scenarios,
> things like "I am used to press f1 on editor xxx to get my documentation"
> , so that we can make an educated decision going forward.
>
> Thanks,
>
> --
> Angel Saenz-Badillos [MS] DataWorks
> This posting is provided "AS IS", with no warranties, and confers no
> rights.Please do not send email directly to this alias.
> This alias is for newsgroup purposes only.
> I am now blogging: http://weblogs.asp.net/angelsb/
>
>
>
>
> "Jason Viers" <bean@beanalby.net> wrote in message
> news:e0eQZDMLGHA.500@TK2MSFTNGP15.phx.gbl...
>
>

Sponsored Links