API docs; functional or pretty?

[Matt Rogers]

On Friday 23 June 2006 03:02, Thomas Zander wrote:
> 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 only looked so far as the module listing and the class list on the side. 
Further feedback on the actual layout of the documentation is below.

> 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?

The fontsize is worse IMO, it's smaller than what's on dev.k.o. and harder to 
read. The use of the brief descriptions is nice when they're there, but since 
some functions lack brief descriptions, it just ends up looking inconsistent 
and isn't as good as a plain list. The fact that the functions and brief 
descriptions have a non-white background helps them stand out more and I like 
that better. The color pattern is better at least in terms of contrast. The 
fact that all of the documentation for a function has a background that is 
offset from the page background makes it easier to read.

Implementing the contrast between the page background and the function 
documentation background would be great to have on dev.k.o. Perhaps a light 
gray could be used there?

>
> > > 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.
>

I don't look in the header files. If the classmapper doesn't find it, then I 
navigate there manually, since I already have a good idea where everything 
is. Yes, not the most efficient way, but it's habit, so I continue to do it.

I understand that I'm not the only one using the KDE APIs and their 
documentation. I'm not so arrogant to think that I'm the only person using 
them. I can only present to you how I use them and my opinion on ways to 
improve them, so don't get your panties all in a bunch because I gave you an 
opinion which you asked for.

btw, the person who commented in your blog decided to google instead of using 
KDevelop's (poorly done) documentation tab. IMHO, that's completely different 
than googling because dev.k.o isn't good enough. 

> > > 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.
>

Cool. We should probably do that then. Perhaps we can have the documentation 
generation on ktown altered to publish those somewhere?

> > 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.
>

I understand what the idea with the list is, and I'm saying that I don't think 
it's better. I also offered a few different solutions, based (or tainted, 
however you feel like thinking about it) on my experience with using the API 
docs that I feel would improve the situation. 

To me, the color coding is non obvious. It might be better to group them into 
Documented and Undocumented categories in order to provide separation, but 
then it becomes harder to search in the list since you have to know whether 
or not the class is documented. An interesting problem.


> > > 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)?

Helps more often than hurts. Mostly due to the link after the inheritance 
diagram which provides a list of all members, even those in the inherited 
class if doxygen knows about it.

As noted in another post, the inheritance diagrams are missing from the 
koffice docs. Those are nice to have.


> - 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?

for me, the short text clutters up the function listing, and IMHO it should 
not be generated in the function listing since not all functions have 
short-text docs. Better seperation between the functions in the list and/or 
alternating color coding would help here since it would make the list easier 
to scan making the lack of short-text for some functions easier to handle.

Most of the time, if I need the documentation of the function, the brief 
description wouldn't tell me what I want to know, so having that in the 
function list vs. having to click on the method name and waiting 

> - 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.
>

I use it. 

> 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.

I only use the docs. If the docs don't provide enough information, I'm forced 
to read the code, and I generally do that by clicking the link to the code 
provided by doxygen, since I'm already there.
--
Matt