On 01/24/12 06:46, Albrecht Schlosser wrote:
> On 23.01.2012 22:54, Greg Ercolano wrote:
>> One of the things I liked about the old 1.1.x docs
>> was we were able to make comments against the docs.
>> Kinda handy for users.
>
> ... to ask support questions and make suggestions for changes
> where they don't belong ;-)
Ha, yes, good for users, but bad for devs who expect STR's
for all suggs.
Thing is, doc comments fill a gap; users are more likely
to make a comment than report an STR:
o People who wanna complain about something
want to be heard. Adding a comment in the docs
is sure to be seen, and can be a freeform complaint,
whereas an STR is mostly just seen by devs and not
other users. (Often doc comments are more 'emotional'
because their frustration level is fresh ;)
o I think many doc bugs or usage problems go unreported
as STRs because folks often don't feel motivated to
switch gears while they're programming to fill out a
bug report. Sometimes comments might raise false alarms,
but devs or other users can reply showing the "fix".
o Sometimes users want to point out something that is
perhaps not a bug or a doc mod request, but a gotchya
they ran into that they would never report as an STR.
o Folks can help each other in the comments forum,
which can be handy.
o Devs can notice issues in these comments forums
that might show a trend of usage issues that may
indicate designs should change.
When folks run into issues, its easy to say 'hey, I had
to do this to make things work' or 'there's a bug in the docs
where it says xxx'. I'm almost sure we miss 90% of such feedback
because folks won't make the extra effort to report these things
as a bug report. They're just trying to move on through their day.
I know I for one will report problems I run into with the
microsoft API through their documentation feedback forum.
But I never bother to report it through their bug system.
Doc comments are kinda nice, cause it's contextual.
For instance, being a dev on Fl_Table, it's easy for
me to keep an eye on Fl_Table related comments, b/c I often
refer to the docs on the website.
>> Not sure how to pull this off with doxygen, but perhaps
>> we can make a post-process for our doxygen website pages
>> that hooks some HTML at the bottom of all the doxygen pages
>> that allows users to comment.
Perhaps we can make our own hidden html comments in the
doxygen docs. This is something our website docs post process
could search and replace with our appropriate "comments" html code.
So for instance, at the bottom of a widget's source code, we could have:
<!-- FLTK_COMMENTS_MARKER: Fl_Widget -->
..that would get inserted into the doxygen html docs.
This would be ignored by web browsers if built locally
on a user's machine, but our website post process would
insert a blob of html that adds a comment section for the Fl_Widget.
This way, no matter what doxygen's hashing method is used
for filenames, we just search and replace all of their html
looking for that special marker.
IIRC there's a way to insert raw HTML code into doxygen docs
which should make it through doxygen's html generator unmolested,
so our post process can detect it. Should be a simple bit of perl.
Perhaps one issue though is with spam.
I don't think comments are moderated, so not sure how
we can keep spammers out, other than capatchas or logins or
some such.
_______________________________________________
fltk-dev mailing list
fltk-dev@easysw.com
http://lists.easysw.com/mailman/listinfo/fltk-dev
