UX Toolkit Document -- PDF Version

[Paul Zablosky]

Thank you Anastasia, those are all valuable suggestions.  Regarding the 
HTML export option, I did experiment with it a bit. It creates a zip 
file of all the pages, in individual files. It includes both comments 
and attachments, so it is more complete than the PDF version.  I agree 
that we should keep our eyes open for other ways of extracting content 
from Confluence. I see that others have tried to address our problem. 
The  PDF Documentation Generator 
<http://confluence.atlassian.com/x/3gByAQ> plugin is an example of 
efforts in this area.

Paul

Anastasia Cheetham wrote:
> 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.
>
>   

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-work/attachments/20080516/a462c1a3/attachment.html>