Issue 79365 - Suggestions for improving the readability of autodoc-generated IDL reference
Summary: Suggestions for improving the readability of autodoc-generated IDL reference
Status: ACCEPTED
Alias: None
Product: App Dev
Classification: Unclassified
Component: sdk (show other issues)
Version: 3.3.0 or older (OOo)
Hardware: All All
: P3 Trivial
Target Milestone: ---
Assignee: AOO issues mailing list
QA Contact:
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2007-07-08 13:31 UTC by Frank Schönheit
Modified: 2013-02-24 20:55 UTC (History)
4 users (show)

See Also:
Issue Type: ENHANCEMENT
Latest Confirmation in: ---
Developer Difficulty: ---


Attachments

Note You need to log in before you can comment on or make changes to this issue.
Description Frank Schönheit 2007-07-08 13:31:11 UTC
Cp.
  http://dba.openoffice.org/test/DataSource.html#Settings
vs.
  http://dba.openoffice.org/test/DataSource_new.html#Settings

In my sometimes not so humble opinion, the second version is more readable than
the first one, with less distraction for the reader's attention, and less geeky
techno-babble which makes the document look "go away" for the innocent casual
reader.

The first version is the normal result of a autodoc run, in the form as it would
appear in the online IDL reference (it's from a CWS of mine, so the exact
content isn't online, yet, but this doesn't matter here).

The second document is a copy of the first, with a number of changes I did,
which IMO result in a better accessibility of the document. In particular, what
I did, and suggest to do by default in autodoc, is:
- omit all occurances of ::com::sun::star:: in all fully-qualified
  identifiers
  Reasoning: Those namespaces do not carry *any* information for the reader.
  All identifiers are inside this namespace, so there is no gain in
  mentioning this again and again and again and again. Instead, the
  constant repeating of those technical terms is scaring for the less
  experienced reader, and distracting to the eyes of probably most of the
  other readers.
- even omit all other namespace references, and put this information
  into a "title" attribute. That is, instead of writing
  ::com::sun::star::beans::XPropertyState, I just wrote XPropertyState, which
  is still linked, and displays "::com::sun::star::beans::XPropertyState"
  when hovering it with the mouse.
  Reasoning: Again, I'd claim that the namespace information is not *that*
  interesting for most (though certainly for some) readers that *all* readers
  should be bothered with it. Instead, the main and most important information
  is the mere type name, which is all which should be displayed by default.
  Whoever is interested in more details of this type (and cannot deduce it
  from the context), can easily click the link, or simply hover it, to
  get this additional information.

Note that so far, what I suggest here is pretty consistent with what for
instance the Java online document does - there, you rarely find fully qualified
types, except in the initial inheritance diagrams.

A third thing I did in the second document will be covered by a separate issue,
since I in fact consider it a bug, not a missing feature.

Now, if you (hopefully :) agree that the second version is more accessible than
the first one, consider
http://dba.openoffice.org/test/DataSource_new_new.html#Settings. I did an
additional relaxation there:
- Instead of writing PropertyAttribute::REMOVEABLE (where both
  PropertyAttribute and REMOVEABLE are linked), I only write REMOVEABLE,
  with the tooltip being
  "::com::sun::star::beans::PropertyAttribute.REMOVEABLE".
  That is, for all members of enumerations and constants groups, I omitted
  the name of the enumeration/group, and only showed the member name.
  Reasoning: In a lot of cases where I use such links to such members,
  the enclosing name is irrelevant, since it can be obtained from the context.
  That is, a sentence like
    "The property must not have the TRANSIENT attribute."
  it's completely superfluous to write
    "The property must not have the PropertyAttribute::TRANSIENT attribute."
  This is writing the same thing ("attribute of a property") twice.
  It might be that this change is not a good idea in general, but I think,
  usually it *is*. So, I suggest to either let autodoc do this by default,
  or to at least provide the writer of the documentation the possibility to
  force autodoc to do it for a given entity.



To make the above long story short :)

I suggest omitting all unnecessary namespace and identifier information in the
generated IDL reference. They're distracting, flow-breaking, of secondary
interest for most readers, sometimes even completely superfluous, and repelling
for a certain class of less technical readers.
Comment 1 Frank Schönheit 2007-07-08 13:32:51 UTC
Should have been SDK, not UDK, sorry.
Comment 2 Frank Schönheit 2007-07-08 13:41:03 UTC
cc'ing UFI, in the hope to get some support :), backed by his expertise as
technical writer. Also like to cc Clayton Cornell, but don't know his OOo
account name.
Comment 3 Uwe Fischer 2007-07-09 08:27:11 UTC
for Clayton
Comment 4 smaug42 2007-07-09 09:05:38 UTC
Assigning back to fs.... and putting myself on cc.

It definitely makes the document more readable to omit the unnecessary namespace
and identifier info in the IDL docs.
Comment 5 Frank Schönheit 2007-07-09 09:13:22 UTC
Then back to np, who is to implement this if accepted.
Comment 6 nikolai.pretzell 2007-07-09 11:58:18 UTC
> omit all occurances of ::com::sun::star:: in all fully-qualified
  identifiers
> even omit all other namespace references, and put this information
  into a "title" attribute
> for all members of enumerations and constants groups, I omitted
  the name of the enumeration/group, and only showed the member name

No objections from my side. I just would like to hear jsc's opinion as well.
Juergen?

Comment 7 jsc 2007-07-09 16:28:19 UTC
i agree 100% with Frank and would like to add one more.

I would remove the com::sun::star namespace in the overview tables as well. Only
the next module is a link and provide some more useful info. Why not removing
the  the namespace here and provide the info in the title attribute as well. 
Comment 8 nikolai.pretzell 2008-06-09 15:12:13 UTC
re-targeted to 3.1
Comment 9 nikolai.pretzell 2008-12-23 12:36:37 UTC
.
Comment 10 nikolai.pretzell 2009-10-27 10:52:41 UTC
I see this has been several times retargeted. So, I put it on my list for 3.3.
Comment 11 jsc 2009-10-28 07:31:24 UTC
i would like to add one more feature request.

We should add a summary of inherited methods, properties etc. as Java did it.
You know the sections "Fields inherit from ..." or "Methods inherited from".
This would help to shorten the navigation and would speedup the search in the
use of the reference docu. It's based on user feedback from real life
customers/users. 
Comment 12 thorsten.ziehm 2010-11-08 14:56:26 UTC
OOo 3.3 is nearly final. Therefore I change the target of this issue to OOo 3.x.