UX Toolkit Document -- PDF Version

[Anastasia Cheetham]

Paul, I'll echo Colin's thanks for this post - very thorough!! My  
comments are inline below:


On 15-May-08, at 8:00 PM, Colin Clark wrote:

> On 15-May-08, at 6:59 PM, Paul Zablosky wrote:

>> 	• 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.

The wiki export process also allows for an HTML version - I wonder if  
this might provide the snapshot we'd like, but in a format that is a  
bit more amenable to the wiki format. I haven't looked at what the  
HTML output is like yet (I don't know if it's a single HTML file or  
multiple files, or what it might look like printed), but it might be  
worth exploring.

>> 	• Can we achieve the quality of manual we want with the editorial
>> resources we have available?
>
> Our editorial resources are pretty scarce

Perhaps we can put a call out for volunteers who might have the time  
and inclination to help?

>
>> 	• 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.

It might help a bit to encourage slightly shorter pages, chunked up a  
bit more? Even on the wiki itself, I find some of the pages very long.  
One of the nice thing about a wiki is the interconnections - you can  
break a page up into a number of pages and maintain the relationships  
between them.

>>  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.

There are many plugins available for Confluence - MS Word export  
macros, more sophisticated PDF export plugins. It would be great if we  
had someone with the time to investigate whether or not there is  
something that could help us improve the quality of an exported  
document.

> 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.

This might be fine, as long as readers are aware that the wiki is  
(ideally) kept up to date with the latest and greatest version of the  
code, and that it might not map directly onto the most recent released  
version.

> 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 have tried to do this a little bit with the API documentation  
already. It would probably help with the rest of the documentation, too.

-- 
Anastasia Cheetham                   a.cheetham at utoronto.ca
Software Designer, Fluid Project    http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto