Hello,
I've added a new FAQ to the Wiki FAQ and a note to the main comment
page. Certainly can't hurt. I think we should still have doc-specific
instructions on each comment page, though (as opposed to pointing to the
FAQ), providing the exact file name(s), etc. of the specific content
we're asking people to review.
http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishDocs
http://wiki.glassfish.java.net/Wiki.jsp?page=FaqViewAttachment
Gail
Dixie Pine wrote:
> saying it better than I did...
>
> On 10/10/08 12:08, June.Parks_at_Sun.COM wrote:
>
>> I think the explanation of how to open the attached PDF is most useful
>> on the pages that actually have PDFs attached. Adding the explanation
>> on the main docs page probably wouldn't hurt, but it would be likely
>> to be ignored.
>>
>> June
>>
>> On 10/10/08 11:45, Paul Davies wrote:
>>
>>> Hi,
>>>
>>>> I don't think this will help at all. My reviewer didn't even look on
>>>> the AG page, much less the main doc comment page with more lines
>>>> that will push the meaty links out of view.
>>>
>>> Well, it might not help *your* reviewer, but that's no reason to omit
>>> information that reviewers who are following the review process as
>>> originally conceived might find useful. Remember, the whole point of
>>> using the wiki, rather than private email exchanges, for reviews is
>>> to keep the review process open and visible to the entire community.
>>> Assisting reviewers in not even looking at the wiki undermines this
>>> process.
>>>
>>>> I notice that if people have to scroll before they see any meat,
>>>> they think it's not there.
>>>
>>> Perhaps one could put the instructions *after* the "meaty" links, and
>>> maybe include a meaty link to the instructions.
>>>
>>>> We are so impatient now, we fly off to something else before looking
>>>> (or reading) what's right there.
>>>
>>> And how can we mitigate the effects of such impatience? The best we
>>> can do, I think, is to redirect the impatient reviewer to helpful
>>> information that they might have initially overlooked. As writers, we
>>> know that nobody reads the docs *unless they have to*.
>>>
>>>> Doc people need to face that and stop putting so much non-meat at
>>>> the top of a page. We love words too much.
>>>> IMHO
>>>
>>> It's not a question of love of words. It's more a question of words
>>> being necessitated by counterintuitive user interfaces.
>>> Unfortunately, the limitations of technology that we are using to
>>> conduct these reviews require words to explain how to overcome these
>>> limitations. In the absence of better technology, I don't see what
>>> else we can do.
>>>
>>> Regards,
>>> -Paul
>>>
>>>>>> On 10/09/08 17:02, Gail Risdal wrote:
>>>>>>
>>>>>>> Hello,
>>>>>>>
>>>>>>> Per the question below, I think all of our doc comment wiki pages
>>>>>>> should have instructions about how to access the attachments. I
>>>>>>> know some of them already do, but for the rest, could you add
>>>>>>> that info to your respective pages when you have a chance?
>>>>>>>
>>>>>>> Other reviewers might be having trouble with this but just aren't
>>>>>>> asking about it - we certainly don't want to put up roadblocks or
>>>>>>> discourage anyone from doing a review.
>>>>>>>
>>>>>>> Thanks,
>>>>>>> Gail
>>>>>>>
>>>>>>> -------- Original Message --------
>>>>>>> Subject: Re: missing document in GlassFish wiki
>>>>>>> Date: Thu, 09 Oct 2008 16:55:39 -0700
>>>>>>> From: Gail Risdal <Gail.Risdal_at_Sun.COM>
>>>>>>> Reply-To: users_at_glassfish.dev.java.net
>>>>>>> Organization: Sun Microsystems
>>>>>>> To: users_at_glassfish.dev.java.net
>>>>>>> References:
>>>>>>> <730700800810091532h58e681efie57018444fe154c6_at_mail.gmail.com>
>>>>>>>
>>>>>>> Hi Sarah,
>>>>>>>
>>>>>>> I agree - it's not that easy to find the attachments! Here's what
>>>>>>> you
>>>>>>> need to do (and we'll make this clearer on those review pages):
>>>>>>>
>>>>>>> 1. On the wiki page for a particular doc, click the Attachments
>>>>>>> link at
>>>>>>> the bottom of the page.
>>>>>>> 2. In the "List of attachments" box, select the .pdf file (the
>>>>>>> file name
>>>>>>> for the JRuby attachment, for instance, is JRUBYAPPDG.pdf).
>>>>>>> 3. In the "Image preview" box, click "Click to load attachment."
>>>>>>> The PDF
>>>>>>> is displayed. (No, not very intuitive! Or, to put it another way,
>>>>>>> intuitive once someone points it out to you.)
>>>>>>>
>>>>>>> Hope this helps.
>>>>>>>
>>>>>>> Gail
>>>>>>> ++++++
>>>>>>> GlassFish Documentation
>>>>>>>
>>>>>>> Sarah kho wrote:
>>>>>>>
>>>>>>>> Hi
>>>>>>>>
>>>>>>>> Thank you for reading my post
>>>>>>>>
>>>>>>>> I think some documents are missing from GlassFish wiki for
>>>>>>>> example in
>>>>>>>> http://wiki.glassfish.java.net/Wiki.jsp?page=JRubyOnRailsForGlassFish
>>>>>>>>
>>>>>>>>
>>>>>>>> it clearly says that "The June 2008 version of this document is
>>>>>>>> available in PDF format as an attachment to this page. This
>>>>>>>> version applies to GlassFish v3 Technology Preview 2 (TP2)." but
>>>>>>>> nothing is attached to the page.
>>>>>>>>
>>>>>>>> many of GF V3 documentation pages has no PDF file attached while
>>>>>>>> they are talking about it.
>>>>>>>>
>>>>>>>> Thanks
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> ---------------------------------------------------------------------
>>>>>>>
>>>>>>> To unsubscribe, e-mail: users-unsubscribe_at_glassfish.dev.java.net
>>>>>>> For additional commands, e-mail: users-help_at_glassfish.dev.java.net
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> ---------------------------------------------------------------------
>>>>>>>
>>>>>>> To unsubscribe, e-mail: docs-unsubscribe_at_glassfish.dev.java.net
>>>>>>> For additional commands, e-mail: docs-help_at_glassfish.dev.java.net
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: docs-unsubscribe_at_glassfish.dev.java.net
>>>>> For additional commands, e-mail: docs-help_at_glassfish.dev.java.net
>>>>>
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docs-unsubscribe_at_glassfish.dev.java.net
>> For additional commands, e-mail: docs-help_at_glassfish.dev.java.net
>>