[cairo] Suggestion to add some links

[Daniel Goldman]

> 2010/8/19 Daniel Goldman <dagoldman at yahoo.com>:

> > PS - I've  been thinking to propose maybe moving from inline source 
>documentation
> >  (gtk-doc / doxygen) to a wiki. I saw this proposed on a cairo "summer of  
>code"
> > page. I would not be in favor of switching to doxygen (if that's  the 
>suggestion)
> > without strongly considering using a wiki first. I would  not be in favor of 
>any
> > change without a lot of thought, because a lot of  work would be involved.
> 
> Misleading documentation is worse than no  documentation. Having that
> in mind, using a wiki for reference documentation  is a very bad idea.
> - After you make changes to the code, you need to go and  change X
> pages of the wiki. This is unnecessary overhead. Some people  will
> inevitably forget to do it, because it requires you to use a  different
> application (text editor vs. browser).
> - What should the wiki  describe - the latest stable or the latest dev
> version? In the first case,  there would have to be a documentation
> frenzy just after each stable release.  In the second, the wiki would
> only be useful for other Cairo developers and  people using bleeding
> edge versions. Inline docs don't have this problem,  because the docs
> are contained in the commits that introduce new functions or  change
> the behavior of existing ones.
> - You send a patch that changes the  behavior of some function. When do
> you update the wiki? If you do it right  away and your patch is not
> accepted, we end up with misleading documentation.  If you do it later,
> it's very likely you'll forget to do it and we end up  with misleading
> documentation.
> 
> Inline docs ensure two important  things:
> - Every version of the source contains documentation that  describes
> the behavior of that particular version of the source.
> - When  the behavior of a function changes, the docs change in the same
> commit. There  is no moment when the docs are out of sync with the
> source.
> 
> Wikis are  excellent for tutorials, blueprints, high-level descriptions
> of the concepts  used in the code, mathematical theorems underlying the
> operation of the code  - things that don't need to closely follow the
> state of the source code. For  reference documentation, they are
> dangerously inadequate.
> 
> Regards,  Krzysztof
>

I don't think it's as black and white as you portray. "wiki for reference 
documentation  is a very bad idea" and "dangerously inadequate" seem like 
exaggerations.

There are advantages of inline documentation, as you point out. But it goes the 
other way too.

http://cairographics.org/summerofcode/ideas/ recommends the same idea of using a 
wiki for the reference docs. At least that's how I interpret it. They call it 
"easy". I would call it "medium".

To address your points:

*** "Unnecessary overhead" - It is easy to make changes to a wiki. I think most 
people are able to handle an editor and a browser. I would call it necessary 
overhead.

*** "Some people will forget" - Some people already are forgetting.

*** "What should wiki describe" - Why not both? If a function is not currently 
part of stable version, a note could say so. Or, a note could be added to an 
existing function that something new is under development in an existing 
function.

*** "Documentation frenzy on new release" - Maybe there might be. Maybe not. I 
don't know.

*** "When do you update wiki after patch" - After patch is accepted. I admit 
this is a negative, since the new documentation is included with patch.

*** "docs never out of sync with source" - I agree with this point.

*** "every version of the source contains it's documentation" - Yes. But how 
often do people use previous versions of the source? What would be the real 
usefulness of this? Good source code should be self-documenting anyway, and 
document the intent if not clear from the function or variable name. See "Code 
Complete".

I would add another advantage of inline docs, maybe the biggest one. gtk-doc 
creates a great index. To understand cairo, I reviewed just every function and 
made my own cheat sheet to make up for some inadequacies in the docs. In that 
process, the index has been my best friend. I don't know if the index could be 
auto-generated with a wiki.

Another advantage of the inline docs might be uniformity, since it's controlled 
by gtk-doc, and by consistent directives. But it currently generates a 
sub-optimal layout, which cannot be edited. And sometimes one size does not fit 
all.

The current docs are not bad. I would give them a B overall. A few pages are 
even exemplary, such as http://cairographics.org/manual/cairo-version-info.html

Here are some problems with the current docs, some of which could be improved 
either with wiki or inline docs:

**** "see also" links mostly missing. This is a big gap, and what I miss most.  
Every function should have at least a few "see also" links for related or 
opposite functions.

*** "synopsis" section poorly formatted and hard to read and interpret. It all 
runs together. If inline docs retained, at least format this part better.

*** poor explanation of concepts. In reviewing the functions, I found many 
ambiguities. I asked about some of these out in previous posts. Another that 
comes to mind is "reference count". I would have just edited the wiki, but it's 
too awkward to do through editing the inline docs. I could post to this group. 
But that's pretty roundabout compared with editing a wiki. Who makes the changes 
once there is a consensus on the discussion group? Searching this group helps 
clear up ambiguities, but then it's too awkward to edit the inline docs.

Here are some advantages of using a wiki for the API docs:

**** Greatly lowers barrier to editing. It's way too much for many people to 
get, edit, and submit the source. It's order of magnitude easier to edit a wiki.

*** Easier to edit. It might be easier to make changes to a wiki than to 
remember obscure inline doc directives.

**** WYSIWYG - Changes to the wiki are immediate. How long does it take to see 
changes to inline docs? This is like the good old days with submitting a job to 
the mainframe job queue and coming back in the next day to see what happened.

**** Allows non-programmers to edit docs. It's well known that most programmers 
are poor at documenting their code. And don't know how to write self-documenting 
code. Good technical writers are usually not good programmers. And vice versa.

**** Better formatting of API docs - The layout of the docs could be easily 
improved with a wiki. Perhaps there is some way to improve the layout of the 
current version. I don't know.

**** Serves as discussion. Questions or unresolved issues can be easily inserted 
into the wiki text. Others can see and resolve them.

Since there are so many open source projects, I imagine there is already a 
consensus about how to write API docs. If the consensus is gtk-doc / doxygen 
better than wiki, I'm certainly not going to argue with that.

Anyway, as the post title indicates, the original point was to add a few basic 
links to make the cairo web site easier to navigate. I hope that's a no-brainer.

Thanks,
Daniel