I'm in, I'll try to document and clean
up my documentation bugs in ISD in a near future!
I agree with Barak, it would be great to have links from each
class to all examples that use them. Personnally, I like hands-on
approaches, so I tend to look at examples to see how things work.
If we had examples for most classes that aren't experimental, that
would be great and lower the learning curve. Then again, who has
the time to write them...
Ideally, in a few years, it should look like this http://eigen.tuxfamily.org/dox/
(search function is as bad there as well)
About the doxygen search function: I use it to look for a specific
function whose name I know. It however doesn't work for names with
underscores in them. It would definitely be amazing to have a
solution for that, but it seems difficult and complicated.
Just to help those who aren't in the salilab's daily discussions:
Are you all planning to use git and move everything to git now?
Le 06/08/12 21:40, Barak Raveh a écrit :
1) Daniel, I think it is a nice idea to add these
autolinks
2) I am also really happy about the renewed interest in
documentation. A bunch of us (Daniel, Riccardo, Dina, myself)
have already started. If you want to help, let us know. We need
all the help we can get.
B
On Mon, Aug 6, 2012 at 12:31 PM, Daniel
Russel <drussel@gmail.com>
wrote:
In terms of specific doc additions, do people think it would
be useful to have:
- links from each class to all examples that use the class
(or, rather, use the name of the class)
- links from each class to all functions that take or return
the function
I had an implementation of the former, but it was a bit of a
hack and broke.
On Mon, Aug 6, 2012 at 12:26
PM, Daniel Russel <drussel@gmail.com>
wrote:
Cool
to see all this interest in improving the docs,
let's make sure it doesn't peter out :-) One useful
direction to move would be to add more standards for
documentation (to the developer guide) and then
switch to a commit model as outlined in the previous
link so there is someone to poke people to get them
to do the work before it gets forgotten about.
On a related note, I find that when using other
libraries (boost, CGAL, bullet being some recent
example) when I have a question I tend to google for
the answer (as opposed to looking through the docs
directly). Useful hits often include the library
docs, but more often than not other sources such as
the support email lists and q&a sites such as
stackoverflow (probably the single most useful site
with popular libraries). As a result, I would highly
encourage people to email the imp-users list with
questions, rather than email or ask Ben or I, so
that the question and answer get indexed for other
people to see.
Here's
my proposal: Every
function
documentation must
have these entries:
Short
Description: (appears
in
the search page) Detailed
Description:
[Algorithm
Description: in
some cases]
Usage:
Simple
Example:
I agree 100% with this suggestion by
Riccardo. Also, that was a great
example that he used about how the
existing documentation doesn't help
in many cases.
Here is the thing: as it stands now, it is
fine for the lab and close
friends to use IMP, because we can walk
over to Daniel or Ben when we
have a problem and quickly get it answered
(thanks guys!). But the goal
for IMP is to get it distributed globally.
If a lab that doesn't have
any connection to ours wants to use it,
currently nothing but the most
simple functionality will be usable due to
the lack of documentation.
So really the overall impact of the
software is reduced.
A point of comparison is Modeller.
Modeller is used by many labs
without having to email us for tech
support. That's because if you go
to the Modeller website, it not only has a
great tutorial, but also
massive class and method documentation.
Most questions can be answered
by using that documentation as a
reference, and I would argue that the
documentation more than almost anything
else is responsible for
Modeller's widespread use.
The problem is that people don't want to
document their code because
once you get something working, you either
feel great about it and want
to apply it to something right away
instead of writing how it works, or
you're so sick of it that you don't want
to go through each method and
document it, or you say you'll do it later
(but of course, later never
comes). I am as guilty as anyone about
this for lab stuff. Some insight
from my brief time working in industry: I
have to document everything I
write here for IP reasons and there is
a lot going on every day so I don't really
have time to revisit old
code. Therefore I have to document right
away or it's never going to
happen.
I thought Barak's attempt at organizing
this was noble and was sad to
see that people didn't have time to do it,
even if it was just a day or
two. I think another attempt should be
made. Remember that your legacy
as a scientist will be defined in large
part by who uses your code
after you have moved on from the lab.
Therefore a day or two of your
life to document as much as possible will
have a high impact on your
output. We have many lab alumni who spent
five years on a project that
no one else can use because it wasn't
properly documented (I myself am
still trying to make sure this doesn't
happen). Honestly, I think
Andrej should crack down a little more on
this, i.e not signing off on
paper submission until all the code that
was used to do it is
documented, or something like that, but I
imagine he would prefer a
more organic solution.
Another suggestion which might be extreme
is to hire a summer college
intern whose sole job would be
documentation. That would actually get
them to be the IMP expert and if they
wanted to go into our field it
would be a great way to start, and we
would get the benefit of
documented code.