Re: quo vadis, docs

[Stefan Kost <ensonic hora-obscura de>]

Hi Tristan,
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...[1]
> 
> 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.

Stefan

>    - 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,
>          -Tristan
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list