UX Toolkit Document -- PDF Version

[Paul Zablosky]

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
>