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.
_______________________________________________
fluid-work mailing list
[email protected]
http://fluidproject.org/mailman/listinfo/fluid-work
