+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 > [email protected] > http://fluidproject.org/mailman/listinfo/fluid-work Daphne Ogle Senior Interaction Designer University of California, Berkeley Educational Technology Services [EMAIL PROTECTED] cell (510)847-0308 _______________________________________________ fluid-work mailing list [email protected] http://fluidproject.org/mailman/listinfo/fluid-work
