To comment on the following update, log in, then open the issue: http://www.openoffice.org/issues/show_bug.cgi?id=79365 Issue #|79365 Summary|Suggestions for improving the readability of autodoc-g |enerated IDL reference Component|udk Version|current Platform|All URL| OS/Version|All Status|NEW Status whiteboard| Keywords| Resolution| Issue type|ENHANCEMENT Priority|P3 Subcomponent|documentation Assigned to|np Reported by|fs
------- Additional comments from [EMAIL PROTECTED] Sun Jul 8 12:31:11 +0000 2007 ------- 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. --------------------------------------------------------------------- Please do not reply to this automatically generated notification from Issue Tracker. Please log onto the website and enter your comments. http://qa.openoffice.org/issue_handling/project_issues.html#notification --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
