Re: quo vadis, docs
- From: Stefan Kost <ensonic hora-obscura de>
- To: Tristan Van Berkom <tvb gnome org>
- Cc: Gnome Release Team <release-team gnome org>, Dan Winship <danw gnome org>, Luis Villa <luis tieguy org>, desktop-devel-list <desktop-devel-list gnome org>, gnome-doc-list <gnome-doc-list gnome org>
- Subject: Re: quo vadis, docs
- Date: Sun, 15 Feb 2009 21:12:03 +0200
Tristan Van Berkom schrieb:
> On Mon, Feb 9, 2009 at 11:52 AM, Luis Villa <luis tieguy org> wrote:
>> Amen. I've often felt developers should be required to document their
>> own UI changes :) Heck, simply asking 'what does this dialog mean'
>> would be useful a lot of the time...
> Luis do you write software ?
> Not that its important that you do, but just to clarify the issue;
> "simply asking what does this dialog mean" in the long run usually means:
> - Take a screen shot of the dialog
This is solveable. I execute all dialog in my software via unit tests on a
virtual framebuffer and take screenshots. This way by running "make check" I
have up-to-date screenshots. They are even scales to 75% as the doc-guide
recommend. Only the drop-scadow is rendered with imagemagic, as I am to lazy to
write that for the pixbuf. One more advantage of this is that you can easily
generate the screenshots even for different locales and/or themes.
> - Open the html or whatever the docs are written in
I was wondering if it would help if we document dialogs in the code as special
comments as well (like we do for api) and use a gtk-doc a like approach to
extract them. That might not work for everything.
> - take time to format the docs/text/images in a readable way
> - take time to properly describe your feature or functionality
> - take time to write a healthy ChangeLog entry for your
> docs commit.
> I am going to generalize here and guess that if you are not GTK+,
> and you are not epiphany or gimp - then its pretty much safe to
> say you are a one man team plus the occasional extra guy, or
> a few randomly submitted patches (which often generate more work
> for the maintainer than bugs fixed or features implemented) - you can hardly
> find time to update the website when you make a release, much less
> spend time writing user docs.
> Sorry I'm starting to run my trap here, I tend to take it to heart
> when time and time again I find our manpower is seriously overestimated
> (which must also be a good thing, if the mere handful of dudes we are
> hacking code managed to accomplish so much and seem like
> such a big team).
> Cheers all,
> gnome-doc-list mailing list
> gnome-doc-list gnome org
] [Thread Prev