UX Toolkit Document -- PDF Version

[Daphne Ogle]

+1 for a documentation page.  Shall we add a task to jira that we can  
prioritize in an upcoming iteration?

-Daphne


On May 16, 2008, at 10:09 AM, Paul Zablosky wrote:

> Colin,
>    Thank you for your response.  Your comments echo a number of
> thoughts that I had while I was reviewing the material.  I think  
> that a
> productive approach would be to follow your suggestion of a
> documentation page that references the wiki pages in an organized
> fashion.  We could experiment with building this initially in the wiki
> itself.
>
> Regards,
> Paul
>
> Colin Clark wrote:
>> Paul,
>>
>> This is an very helpful and detailed analysis of the problem. Thanks
>> so much for documenting it. Some quick thoughts below; hopefully
>> others will share their comments, too.
>>
>> On 15-May-08, at 6:59 PM, Paul Zablosky wrote:
>>> All this sounds a bit negative.  I don't mean it to be so, I'm just
>>> trying to lay out the limitations of what we're working with  
>>> here.  I
>>> had hoped that with a bit of juggling in the wiki I could make the
>>> serialized version a lot more readable, but I find myself stymied by
>>> the lack of ways to explicitly manifest the document's structure
>>> through the PDF extract process.
>>
>> Good point, and it doesn't sound negative. We originally chose to
>> auto-generate our documentation package from the wiki as a stop-gap
>> solution until we had a better way to share the material with our
>> users. It's definitely not ideal.
>>
>>> Having looked at the problem from a number of viewpoints, I'm
>>> appealing to the Fluid community for suggestions on how we should
>>> proceed. Consider the following questions:
>>>    • Is a printable manual really valuable to our target audience?
>>
>> Printability is less of a goal for me. The initial reason for  
>> creating
>> a PDF was to ensure that we had a snapshot of the documentation at a
>> particular point in time to correspond with the tagged release. Since
>> our wiki is always evolving, we wanted a way for users to ensure that
>> they had the correct version of the documentation.
>>
>>>    • Can we achieve the quality of manual we want with the editorial
>>> resources we have available?
>>
>> Our editorial resources are pretty scarce, and we've found that  
>> it's a
>> lot of work to publish the PDF. So we probably can't achieve our
>> desired level of quality with this approach.
>>
>>>    • Does it make sense to ask wiki-page authors to consider how
>>> their entries will work as serialized text with all the other pages
>>> -- and possibly curtail their exploitation of the capabilities of  
>>> the 
>>> wiki?
>>
>> Probably not. The real value of a wiki is its highly interrelated
>> nature. Lots of hyperlinking and dynamic macros.
>>
>>> In summary, let me say that the Fluid wiki pages contain a lot of
>>> well-presented and valuable information.  There is a room for
>>> editorial improvement -- wiki gardening is never at an end -- but  
>>> the
>>> overall quality of the material is high.  Producing a coherent
>>> printed manual from the material, however, is a challenge that our
>>> technical tools aren't quite up to.  We have to consider what we can
>>> do about this.
>>
>> I haven't had a lot of time yet to think about an alternative
>> approach, but my sense is that we should move away entirely from
>> creating a PDF. Perhaps we can explore some other means of promoting
>> selections from our documentation into a more suitable form.
>>
>> From the technical side, I know that the jQuery community creates all
>> their technical documentation right in the wiki. I'm curious to hear
>> how they handle versioning. I'll ask.
>>
>> From the non-technical perspective, I would guess that versioning
>> isn't even very important--users of the UX Toolkit documentation
>> probably want the latest and greatest, irrespective of the version of
>> Infusion they're running.
>>
>> Off the top of my head, one idea would be to create a more visible
>> Documentation page on http://fluidproject.org that provides a
>> carefully chosen set of links into the wiki. That way, we can embrace
>> the living nature of the wiki while providing a bit of extra
>> information architecture to help users find the most important
>> information easily.
>>
>> I'd love to hear other suggestions for lightweight alternatives to
>> generating a full PDF document from our wiki.
>>
>> Colin
>>
>> ---
>> Colin Clark
>> Technical Lead, Fluid Project
>> Adaptive Technology Resource Centre, University of Toronto
>> http://fluidproject.org
>>
>
> _______________________________________________
> fluid-work mailing list
> fluid-work at fluidproject.org
> http://fluidproject.org/mailman/listinfo/fluid-work

Daphne Ogle
Senior Interaction Designer
University of California, Berkeley
Educational Technology Services
daphne at media.berkeley.edu
cell (510)847-0308