You are viewing a plain text version of this content. The canonical link for it is here.

Posted to derby-dev@db.apache.org by Laura Stewart <sc...@gmail.com> on 2006/08/16 00:57:50 UTC

10.2 documentation reviews

Now that we have a Beta for Derby 10.2, we need to have a final review
of the documentation to ensure that all of the features are documented
and that the information is complete.

The Alpha versions of the documentation listed at
http://db.apache.org/derby/manuals can be used for these reviews.

What we need is a method for people to sign up for the reviews and a way to
log errors, omissions, or discrepancies.

-- 
Laura Stewart

Re: 10.2 documentation reviews

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Kathey Marsden wrote:
> John Embretsen wrote:
>> Jean T. Anderson wrote:
>>
>>>>> I initialized Wiki feedback pages for the 10.2 doc review here:
>>>>>
>>>>>   http://wiki.apache.org/db-derby/TenTwoDocReview
>>
>> [SNIP]
>>
>>> Can a MoinMoin table cell cross lines easily? i.e., for adding sample
>>> code, a paragraph of text or whatnot?
>>
>> I'm not exactly sure what you mean, but if you mean something like
>> html rowspan, it seems easy. See
>>
>> http://wiki.apache.org/db-derby/HelpOnTables

Here's a good example from the 10.1 review of what I mean:

https://issues.apache.org/jira/browse/DERBY-380#action_12314152

So, detailed comments that include specific fixes to the sample code.
Not something you can fit into a MoinMoin table cell.

> If a comment is extensive.  One option might be to send a mail to
> derby-dev with the changes,  put a summary in the table and add a link
> to the email archives.
> 
> Kathey

that might work fine -- and would have the advantage that anybody
searching the mail archives for a given topic might find good info.

 -jean

Re: 10.2 documentation reviews

Posted by Kathey Marsden <km...@sbcglobal.net>.

John Embretsen wrote:

> Jean T. Anderson wrote:
>
>>>> I initialized Wiki feedback pages for the 10.2 doc review here:
>>>>
>>>>   http://wiki.apache.org/db-derby/TenTwoDocReview
>>>
>
> [SNIP]
>
>> Can a MoinMoin table cell cross lines easily? i.e., for adding sample
>> code, a paragraph of text or whatnot?
>
>
> I'm not exactly sure what you mean, but if you mean something like 
> html rowspan, it seems easy. See
>
> http://wiki.apache.org/db-derby/HelpOnTables
>
>
If a comment is extensive.  One option might be to send a mail to 
derby-dev with the changes,  put a summary in the table and add a link 
to the email archives.

Kathey

Re: 10.2 documentation reviews

Posted by John Embretsen <Jo...@Sun.COM>.

Jean T. Anderson wrote:
>>> I initialized Wiki feedback pages for the 10.2 doc review here:
>>>
>>>   http://wiki.apache.org/db-derby/TenTwoDocReview

[SNIP]

> Can a MoinMoin table cell cross lines easily? i.e., for adding sample
> code, a paragraph of text or whatnot?

I'm not exactly sure what you mean, but if you mean something like html 
rowspan, it seems easy. See

http://wiki.apache.org/db-derby/HelpOnTables


-- 
John

Re: 10.2 documentation reviews

Posted by Daniel John Debrunner <dj...@apache.org>.

Laura Stewart wrote:

> The advantage to having "DOCS" or "Documentation" in the title is that
> the issues are easier to track when email comments are received. The
> component "documentation" is fine when you are in Jira, but does not
> appear in the title of a comment to a Jira issue in email.... 

The summary for the jira issues get reflected in the release notes and
potentially in other places, I don't want to see those cluttered with
different prefixes when a component is the correct mechanism. With this
precedence we could reach a situation where the subject line is
something like, leaving no visibility for the actual content in an
e-mail client window:

[jira] Created: (DERBY-2032) DOCS IMPROVEMENT 10.2 Minor Urgent ...

> which is
> where I first encounter new issues.  During this part of a release
> cycle, I don't go to the Jira docs issues list, but work primiarliy
> off of the email comments so that I can respond to the comments more
> quickly.

The use of Jira has to be for the whole community, not tailored towards
an individual's requirements. We also have to remember that this is an
open project and our bug summaries may escape far & wide. As an example
changing the summary of a bug to totally change its meaning is a bad
idea. E.g.

DERBY-4332 insert statements don't work with 7 columns

to

DERBY-4332 test updateXXX.java has incorrect logic in sub-case
testBinaryColumns

Between the change some one shipping Derby may have included the text
for DERBY-4332 in their release notes, leading to confusion when their
customer looks up DERBY-4332 in the ASF Jira system.

Dan.

> On 8/16/06, Daniel John Debrunner <dj...@apache.org> wrote:
> 
>> Laura Stewart wrote:
>>
>> > Longer comments should not be entered into the table. Instead a Jira
>> > issue should be created with DOCS as the first word in the title,
>>
>> There is already have a mechanism to indicate the Jira entry is for
>> documentation:  Component of "documentation". Let's not invent a new
>> scheme.

Re: How to email Jira report? ( was Re: 10.2 documentation reviews)

Posted by Laura Stewart <sc...@gmail.com>.

On 8/16/06, Kathey Marsden <km...@sbcglobal.net> wrote:
> Under manage fiters, you can subscribe:
> See:
>
> http://www.atlassian.com/software/jira/docs/v3.6.3/issue_filters.html#Filter+Subscriptions
>
>

Thanks!!

-- 
Laura Stewart

Re: How to email Jira report? ( was Re: 10.2 documentation reviews)

Posted by Kathey Marsden <km...@sbcglobal.net>.

Jean T. Anderson wrote:

>Laura Stewart wrote:
>...
>  
>
>>I know how to create a filter in jira, but how do I have an email sent
>>to me?
>>    
>>
>
>we need help from somebody who has done it. (Help!)  :-)
>
> -jean
>
>  
>
Under manage fiters, you can subscribe:
See:

http://www.atlassian.com/software/jira/docs/v3.6.3/issue_filters.html#Filter+Subscriptions

How to email Jira report? ( was Re: 10.2 documentation reviews)

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Laura Stewart wrote:
...
> I know how to create a filter in jira, but how do I have an email sent
> to me?

we need help from somebody who has done it. (Help!)  :-)

 -jean

Re: 10.2 documentation reviews

Posted by Laura Stewart <sc...@gmail.com>.

On 8/16/06, Jean T. Anderson <jt...@bristowhill.com> wrote:

> I can appreciate your frustration ... docs are caught in the squeeze at
> the very end. Here are a couple suggestions:
>
> 1) Set up a Jira filter that mails you a daily report of doc issues,
> perhaps sorted by most recent activity if that's possible (maybe Jira
> experts can jump in with specific suggestions).
>
> 2) If somebody opens a new doc issue and thinks it needs your urgent
> attention, I see no problem with them forwarding a copy of the notice to
> you offlist with a "wanted to make sure you saw this". I'll do that.
>
> thanks for all the doc work -- we really appreciate it!
>
>  -jean
>

*** (LS) Thanks Jean. These are good suggestions. And I appreciate
your kind words.

I know how to create a filter in jira, but how do I have an email sent to me?

I do feel that it is useful to use a 1 word preface in an issue title
to let people know the basic area that the issue affects, regardless
of whether it is a doc issue or not.  Often feature issues contain the
name of the feature, such as grant/revoke, early on in the title so
that people looking at the email can quickly determine if the email is
something that they want to read.  What I was suggesting was in the
same vein.

But of course I will go along with whatever the Derby community thinks is best.

-- 
Laura Stewart

Re: 10.2 documentation reviews

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Laura Stewart wrote:
> The advantage to having "DOCS" or "Documentation" in the title is that
> the issues are easier to track when email comments are received. The
> component "documentation" is fine when you are in Jira, but does not
> appear in the title of a comment to a Jira issue in email.... which is
> where I first encounter new issues.  During this part of a release
> cycle, I don't go to the Jira docs issues list, but work primiarliy
> off of the email comments so that I can respond to the comments more
> quickly.

I can appreciate your frustration ... docs are caught in the squeeze at
the very end. Here are a couple suggestions:

1) Set up a Jira filter that mails you a daily report of doc issues,
perhaps sorted by most recent activity if that's possible (maybe Jira
experts can jump in with specific suggestions).

2) If somebody opens a new doc issue and thinks it needs your urgent
attention, I see no problem with them forwarding a copy of the notice to
you offlist with a "wanted to make sure you saw this". I'll do that.

thanks for all the doc work -- we really appreciate it!

 -jean

Re: 10.2 documentation reviews

Posted by Laura Stewart <sc...@gmail.com>.

The advantage to having "DOCS" or "Documentation" in the title is that
the issues are easier to track when email comments are received. The
component "documentation" is fine when you are in Jira, but does not
appear in the title of a comment to a Jira issue in email.... which is
where I first encounter new issues.  During this part of a release
cycle, I don't go to the Jira docs issues list, but work primiarliy
off of the email comments so that I can respond to the comments more
quickly.

On 8/16/06, Daniel John Debrunner <dj...@apache.org> wrote:
> Laura Stewart wrote:
>
> > Longer comments should not be entered into the table. Instead a Jira
> > issue should be created with DOCS as the first word in the title,
>
> There is already have a mechanism to indicate the Jira entry is for
> documentation:  Component of "documentation". Let's not invent a new scheme.
>
> Thanks,
> Dan.
>
>

-- 
Laura Stewart

Re: 10.2 documentation reviews

Posted by Daniel John Debrunner <dj...@apache.org>.

Laura Stewart wrote:

> Longer comments should not be entered into the table. Instead a Jira
> issue should be created with DOCS as the first word in the title, 

There is already have a mechanism to indicate the Jira entry is for
documentation:  Component of "documentation". Let's not invent a new scheme.

Thanks,
Dan.

Re: 10.2 documentation reviews : choosing a style

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Rajesh Kartha wrote:
...
> I have updated the http://wiki.apache.org/db-derby/ReferenceManualTenTwo
> page to create:
> - a main table with all major sections in the Reference manual  with
> 'Reviewers' and 'Status' as the
>  other fields.
> - empty subtables for adding comments
> - anchors to subtables

I modified it slightly to more clearly separate the summary section from
the summary details section. If I messed up your strategy, let me know.

> I hope this will make it easier for doc review sign up and providing
> comments.
> 
> Too many things going on, so I am kind of tied up at the moment. Hence
> would appreciate if
> somebody can create similar wikis for the other  Derby documents.

I initialized the other pages with the skeleton of the summary and
subsection details, but don't have time to fill in the level of detail
you put on the page for the Reference Manual.

that should be enough to get people started filling in details as they
spot them.

 -jean

Re: 10.2 documentation reviews : choosing a style

Posted by Rajesh Kartha <ka...@gmail.com>.

Jean T. Anderson wrote:

>Laura Stewart wrote:
>  
>
>>On 8/16/06, Rajesh Kartha <ka...@gmail.com> wrote:
>>
>>    
>>
>>>Laura Stewart wrote:
>>>
>>>The current one looks good. I was thinking  rather than putting all
>>>the comments in one table, if we can divide into multiple tables
>>>based on the main sections of the document:
>>>
>>>      
>>>
>>Either way works for me, I search on section name to locate the
>>filename to be changed.
>>    
>>
>
>Rajesh, how about if you just go ahead and update to what you want?
>
>Do you want to add tables for other books? or would you like me to do a
>base table initialization so folks can get started?
>
> -jean
>
>
>  
>
I have updated the http://wiki.apache.org/db-derby/ReferenceManualTenTwo 
page to create:
- a main table with all major sections in the Reference manual  with 
'Reviewers' and 'Status' as the
  other fields.
- empty subtables for adding comments
- anchors to subtables

I hope this will make it easier for doc review sign up and providing 
comments.

Too many things going on, so I am kind of tied up at the moment. Hence 
would appreciate if
somebody can create similar wikis for the other  Derby documents.

Regards,
Rajesh

Re: 10.2 documentation reviews : choosing a style

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Laura Stewart wrote:
> On 8/16/06, Rajesh Kartha <ka...@gmail.com> wrote:
> 
>> Laura Stewart wrote:
>>
>> The current one looks good. I was thinking  rather than putting all
>> the comments in one table, if we can divide into multiple tables
>> based on the main sections of the document:
>>
> 
> Either way works for me, I search on section name to locate the
> filename to be changed.

Rajesh, how about if you just go ahead and update to what you want?

Do you want to add tables for other books? or would you like me to do a
base table initialization so folks can get started?

 -jean

Re: 10.2 documentation reviews : choosing a style

Posted by Laura Stewart <sc...@gmail.com>.

On 8/16/06, Rajesh Kartha <ka...@gmail.com> wrote:
> Laura Stewart wrote:
>
> The current one looks good. I was thinking  rather than putting all
> the comments in one table, if we can divide into multiple tables
> based on the main sections of the document:
>

Either way works for me, I search on section name to locate the
filename to be changed.
-- 
Laura Stewart

Re: 10.2 documentation reviews : choosing a style

Posted by Rajesh Kartha <ka...@gmail.com>.

Laura Stewart wrote:

>> On 8/16/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>> > Yip added an entry for Reference Manual, which I reformatted to a 
>> table
>> > format incorporating (I hope) comments by Laura and Rajesh.
>> >
>> > how does this look?
>> >
>
>
> This is great. Can you bold the titles of the columns?
>
The current one looks good. I was thinking  rather than putting all
the comments in one table, if we can divide into multiple tables
based on the main sections of the document:

An example:

*Section *- SQL Language Reference - SQL Statements  (Reviewers: Yip, ..)
===================================================

----------------------------------------------------------------------------- 

*Sub Section name                HTML Url/Pdf        Reviewer       
Comment*
----------------------------------------------------------------------------- 

DECLARE GLOBAL           Link                  Yip       Under 
Restrictions on....
TEMPORARY TABLE
statement
----------------------------------------------------------------------------- 

CREATE SCHEMA             Link               Rajesh       Need some 
correction..
statement
------------------------------------------------------------------------------- 


Derby members can add themselves to the Reviewer's list  to indicate
sections being reviewed.

Regards,
Rajesh

Re: 10.2 documentation reviews : choosing a style

Posted by Laura Stewart <sc...@gmail.com>.

Looks just great, thanks!
Please use that format for the other books.

-- 
Laura Stewart

Re: 10.2 documentation reviews : choosing a style

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Laura Stewart wrote:
>> On 8/16/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>> > Yip added an entry for Reference Manual, which I reformatted to a table
>> > format incorporating (I hope) comments by Laura and Rajesh.
>> >
>> > how does this look?
> 
> This is great. Can you bold the titles of the columns?

It's now emboldened -- do feel free to tweak it.

 -jean

Re: 10.2 documentation reviews : choosing a style

Posted by Laura Stewart <sc...@gmail.com>.

> On 8/16/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
> > Yip added an entry for Reference Manual, which I reformatted to a table
> > format incorporating (I hope) comments by Laura and Rajesh.
> >
> > how does this look?
> >

This is great. Can you bold the titles of the columns?

-- 
Laura Stewart

Re: 10.2 documentation reviews : choosing a style

Posted by Yip Ng <yi...@gmail.com>.

The tabular format looks good.  =) Thanks Jean!

On 8/16/06, Jean T. Anderson <jt...@bristowhill.com> wrote:
>
> Yip added an entry for Reference Manual, which I reformatted to a table
> format incorporating (I hope) comments by Laura and Rajesh.
>
> how does this look?
>
> http://wiki.apache.org/db-derby/ReferenceManualTenTwo
>
> If people like this style, I'll initialize tables for the other wiki
> pages.
>
> -jean
>

Re: 10.2 documentation reviews : choosing a style

Posted by "Jean T. Anderson" <jt...@bristowhill.com>.

Rick Hillegas wrote:
> Thanks, Jean, this is great! As you add these pages could you wire them
> into the 10.2 wiki page (http://wiki.apache.org/db-derby/TenTwoRelease),
> perhaps under the "10.2 Documentation Issues" section?

will do -- I had added it to the Upcoming Releases section on the Front
Page -- oops! :-)

 -jean


> Cheers,
> -Rick
> 
> Jean T. Anderson wrote:
> 
>> Yip added an entry for Reference Manual, which I reformatted to a table
>> format incorporating (I hope) comments by Laura and Rajesh.
>>
>> how does this look?
>>
>> http://wiki.apache.org/db-derby/ReferenceManualTenTwo
>>
>> If people like this style, I'll initialize tables for the other wiki
>> pages.
>>
>> -jean
>>  
>>
>

Re: 10.2 documentation reviews : choosing a style

Posted by Rick Hillegas <Ri...@Sun.COM>.

Thanks, Jean, this is great! As you add these pages could you wire them 
into the 10.2 wiki page (http://wiki.apache.org/db-derby/TenTwoRelease), 
perhaps under the "10.2 Documentation Issues" section?

Cheers,
-Rick

Jean T. Anderson wrote:

>Yip added an entry for Reference Manual, which I reformatted to a table
>format incorporating (I hope) comments by Laura and Rajesh.
>
>how does this look?
>
>http://wiki.apache.org/db-derby/ReferenceManualTenTwo
>
>If people like this style, I'll initialize tables for the other wiki pages.
>
> -jean
>  
>