Great work, Jeff, and great ideas. Thanks for doing the research on
adding user comments. I think this is a very valuable feature so it
would be really good if we could figure this out. Let me know if there
is any way I can help.
I also think the indexing is key to "maneuverability" in our docs, a
common complaint I have heard about from new users: how do I find the
documentation for what I'm trying to do? Full text search would of
course be great...
David
Jeff Levitt wrote:
--- Francois Orsini <[EMAIL PROTECTED]> wrote:
Looks good Jeff.
The original Cloudscape documentation had a
fantastic master/global
index file - it was my main front-door to me for any
type of
documentation searching - I could locate anything
real fast and
documents (HTML) were linked as well. I know this
global index file
took a lot of time to build but it did save so much
time when looking
for something in the documentation...
The MySQL online documentation also lets users add
comments to the
documentation - I have to admit it has been useful
when I tried to get
my way around MySQL....
Cheers,
--francois
On 7/26/05, David Van Couvering
<[EMAIL PROTECTED]> wrote:
Ooh, yes, very nice. This is something I have
struggled with in the
past -- I click on a topic, and then to go to
sub-topics I have to
I also very much like the related topics feature.
It would be great if those of us who use the
manuals could "add" related
topics as it becomes clear they are related. It
would be even *nicer*
if this could be done right there online without
having to edit DITA files.
If you look at the PGP documentation you will see
what I mean:
http://www.php.net/manual/en/install.unix.php
at the bottom of the page there is the "add a
note" link. Users can add
notes to the page to provide more details, helpful
hints, or
complaints. There are quite a few helpful notes
added to this page.
Wouldn't it be possible to modify the DITA
template to allow users to
add notes? We could then incorporate useful notes
into the next rev of
the docs.
David
So I've actually been doing quite a bit of research
into doing something like inline comments to the
documentation, and I've run into several issues:
1. Both PHP and MySQL use the same engine for their
inline comments. They use PHP scripting (of course).
The problem is whether we can do that or something
similar on an Apache web site server. I mean this not
in a technical sense (obviously we have the "ability"
to do it), but in a legal sense (whether Apache will
allow it).
2. PHP and MySQL documentation aren't updated nightly
as ours is. If we re-generate all of our
documentation nightly, wouldn't we lose that day's
comments from outsiders? The solution would be to have
the commenting engine store the comments in separate
files outside the content files themselves. But then
what happens if we delete a topic or change it's name?
Lots of infrastructure problems with this solution to
be worked out.
3. Again, if we use outside files to store the
comments, we return to the Apache legality issue. Can
we do things like add and modify files on the Apache
servers? I didn't think we could.
Now related links as we currently use them is another
story. I would define our related links as strictly
links from one topic in a manual to another. As David
requested, I think some sort of web page could be
created that has tables showing the relationships
between topics, and simple check boxes could enable or
disable related links between one topic and another.
I think on a technical level, we would need to have
the engine behind this generate the relationship
tables for each book into separate files, then modify
the ant nightly build to merge the relationship tables
with the ditamap for each book before creating the
output. The issue I see with this is who gets to
modify the tables? Committers? How would one request
a change? Just through a JIRA entry, and then a
committer checks and unchecks the boxes on the web
page?
As for the global index, I think it is possible.
First we have to get individual indexes working for
each manual, which we don't have yet either! Scott
Hutinger and I did some research earlier this year
into implementing indexes but we were never able to
get it completed. If and when we do that, then Global
indexing wouldn't be too far behind. We already have
index entries defined within each topic dita file, but
they are just sitting there for now not implemented
anywhere. Going back to the idea for a web page that
allows for creating and deleting our related links, I
think it could also be possible to create a section
where we can enter, modify, and delete index entries
for each topic.
begin:vcard
fn:David Van Couvering
n:Van Couvering;David
org:Sun Microsystems, Inc.;Database Technology Group
email;internet:[EMAIL PROTECTED]
title:Senior Staff Software Engineer
tel;work:510-550-6819
tel;cell:510-684-7281
x-mozilla-html:TRUE
version:2.1
end:vcard
