API docs; functional or pretty?

[Thomas Zander]

On Friday 23 June 2006 01:29, Matt Rogers wrote:
> On Thursday 22 June 2006 13:00, Thomas Zander wrote:
> they should be both pretty and functional. Documentation that is hard
> to read (or search through) will not be used. Frankly, the KOffice docs
> look like as presented in [3] look like crap, and I wouldn't use them
> if they looked like that.

The best feedback you can give is 'they look like crap'?
Whats better (in readability) on d.ko?  And whats worse?
I listed several items in my blog; which do you think are not well 
researched and end up making things worse?
Have you asked yourself the question that you might get used to it and see 
its actually more readable due to the color patterns, fontsize and 
structuring?

> > b) package based to class based searching.
> > Most devs don't know if a class comes from kdecore or kdeui or
> > whatever, so they end up clicking and searching all. Moreover since
> > the classes without docs don't show up anywhere it tends to be a hit
> > and miss.
>
> with a few exceptions, using "kde: ClassName" works just fine for me,
> so I don't have a good grasp of what you mean here. In most cases I
> don't need to know that a class is in kdecore or kdeui.

I actually have the kdelibs docs and _more_ than half the classes are not 
findable by kde:  None of the namespaces (kio etc) are findable like 
that.
This makes it quite hard for me to believe you are actually never forced 
to look in the header file because, as you state, 'kde:' works just fine.
If you look at the comments on my blog you'll note that people actually 
use google to search for classes. So I do think I found a real problem. 
If you don't suffer from it, then fine. But please note that you are not 
the only developer _using_ kde APIs.

> > c) Better inter-project links.  I can now see (and click on) a parent
> > class even if its in another lib.
>
> that is nice.

I should note that publishing a TAGS file online means other projects can 
link to it.  In my local koffice docs I can see (and click on) the 
KCommand class that several of my classes inherit from.  This has the 
most obvious advantage that in the 'Class Hierarchy' page I see all 
commands next to each other since they all inherit from one class.
They used to be all over the place.

> I don't think the way you've done the API docs in [3] is better. I
> think it's worse actually. Why? Because I have to search for a
> particular class myself in this long list of other classes that I don't
> care about. I think the easiest way to solve this problem is to offer
> htdig searches if htdig is installed.

The idea behind this is to not be dependant on a server side search but to 
have a local list of all classes that you can click on, that has tooltips 
to show the package the class is in and that shows if a name is a class 
or a struct or a namespace.  All without any internet access.
And, most of all, all the red names are never to be found in the current 
docs; not giving feedback on why a search failed means people will lose 
faith in the system and stop using it.

> > What can we do with the problem Adriaan put forth that as long as the
> > docs don't look and behave like the kde - site (which IMO makes them
> > unusable) we can't have them on developer.kde.org?
>
> Come up with something better that makes them both pretty and
> functional.
In your opinion;
- does the current dko way of putting classdoc at the top help or slow you 
down when you look for constructors and public methods (which happens a 
more often)?
- does the current dko way of having no short-text for methods, forcing 
you to click on the method itself (and wait) help you, or slow you down 
in finding the method name you want to use?
- Who uses the overview of libraries on the left?, its too big to search 
visually for the one you want, and due to not using frames you can't use 
search.

Oh, and how often do you _use_ the current docs v.s. reading header files. 
I assume you only use docs since you found the 'kde:classname' way of 
accessing them adequate. But I have to ask since if you don't you proved 
my point of the docs not being used as a proper tool.
-- 
Thomas Zander
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20060623/b26b664d/attachment.sig>