UX Toolkit Document -- PDF Version

[Colin Clark]

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