[more]
On 6/28/06, Jim Harris <[EMAIL PROTECTED]> wrote:
I agree that OOo Documentation and its dev project and support tools could
be improved.
I also agree a Wiki _may_ be a good solution.
However, I have seen no evidence that it is clearly the best solution, or
even that it is what should be done next.
And even if it is, I submit that an unstructured Wiki will add more
problems. A Wiki for a special purpose, such as keeping track of the
documentation-dev resources and their statuses, probably should have some
specific structure and rules, clearly explained (even for someone _not_
already familiar with the problem and/or solution) on its home page.
Aren't there very good, special-purpose tools for supporting the
documentation-development task? I'm no expert, but I would think people,
e.g. the ones on SourceForge, have solved this problem well several times.
The best FOSS solution I'm aware of is Trac, <
http://projects.edgewall.com/trac/>. It's a GUI front-end for Subversion
that, inter alia, adds a very powerful Python-based wiki to Subversion's
repertoire. WebDAV-enabled so editing could be done in OOo, Trac's pages can
be edited natively in wiki syntax, reStructured Text, Textile, or HTML. Also
exports to DocBook, amongst other formats. If you've never worked with
reStructured Text, it would be difficult to explain just how versatile the
"markup" can be, but automatically-generated tables of contents and
formatting/ordering/numbering of footnotes are just the beginning of the
story.
Trac features Python macros, so just about anything that can be done with
Python can be done with Trac. There's also a tool for converting from
WikiMedia to Trac wiki markup.
Wiki formatting can be used in web pages, tickets, and check-in log
messages.
[more]
[EMAIL PROTECTED] 9:03:26 PM 6/27/2006 >>>
G. Roderick Singleton wrote:
> Jean Hollis Weber wrote:
>> If Gary has been unable to tell which attachment is the latest
>> version of a chapter, that is a good example of the difficulties
>> of using the Issue system for keeping track of things, esp. when
>> out of date versions of a chapter are not (can not be?) removed
>> from the issue... and it's hard to tell who is working on what,
>> and what stage a particular chapter has reached.
>
With Subversion an ingredient in the Trac recipe, the ability to manage
document versions isn't going to get any better with any other program.
[more]
Gee with all the dates and times, I would have thought selection pretty
> easy. I guess not. :-(
No, it's not easy. There are far too many notes and items to wade
through, even working backwards through the list. It's too easy
to miss a critical note when scanning through such a long list,
and end up with a file that is earlier than the latest. One can
find what one needs in that issue, and determine which date is
which, and all of that, but it is definitely *not* easy, at least
for someone who is not intimately familiar with the book, as you are.
That's the kind of issue that wiki page linking makes short work of. E.g.,
if there is a wiki page named "OOo Guide Ch. 12" and it includes the code to
display on it "what pages link here?," then the Chapter 12 page will include
a hyperlinked list of every note, other page, etc. that includes a link to
the Chapter 12 page.
[more]
Docs really needs a better system for tracking things. [...]
>> One possibility I can think of is to use a section of the
>> Documentation wiki for tracking. Of course that depends on people
>> actually putting info into the wiki in a timely manner.
>
> A wiki solution would be nice.
I think Jim is right. It needs to be more than just any wiki; it needs a
tool that is really designed for collaborative development of software
documentation. I've got several hundred hours into looking at documentation
development tools. Trac's the best I've seen so far. There's an online
sandbox on the Trac site if you want to play with it.
Best,
Marbux
