[cairo-bugs] [Bug 2798] version-controlled files modified by make'ing cairo

[bugzilla-daemon at freedesktop.org]

http://bugs.freedesktop.org/show_bug.cgi?id=2798





------- Comment #7 from cworth at cworth.org  2007-07-03 09:20 PST -------
(In reply to comment #6)
> And risk having them all outdated.

I don't buy that argument at all.

What's necessary is a culture that mandates that a change or addition
to the semantics of the library be accompanied with an update to the
documentation at the same time. I think we have that culture within
the cairo community now.

Something that helps that culture is a tool that allows a single
"commit" to show both changes to the code and changes to the
documentation as atomic. So that feature I would definitely like. But
I don't think that has anything to do with "documentation in .c
files".

And something that we've been entirely missing out on with the
documentation is a conversation with users of the library/consumers of
the documentation. These are people that might never need to look at
the implementation of cairo, but do very often read the documentation
and are the people most acutely aware of problems in that
documentation.

So I really want to move the documentation to "live" in something like
a wiki, where there is at least a "discuss" page where users can
freely comment on things that were unclear in the documentation, or
things they've learned elsewhere that should be added, etc.

I'll talk more about this on the mailing list soon.

-Carl


-- 
Configure bugmail: http://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug, or are watching the QA contact.