[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [IMP-dev] Fwd: on documentation



Yannick, you are another very important name I forgot, just hard to see across the ocean sorry :) And Jeremey too!Â

About git - it's kinda in the twilight zone now, Daniel already has set a git repository that he keeps in sync with the svn every once in a while, but it might take a little while until we leave svn, probably only following the next release? Daniel? Ben?


On Mon, Aug 6, 2012 at 1:36 PM, Yannick Spill <" target="_blank">> wrote:
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 <" target="_blank">> 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 <" target="_blank">> 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.


On Mon, Aug 6, 2012 at 11:45 AM, Dave Barkan <" target="_blank">> wrote:

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.

(tl;dr ?)

thanks,
dave









_______________________________________________ IMP-dev mailing list " target="_blank"> https://salilab.org/mailman/listinfo/imp-dev


_______________________________________________
IMP-dev mailing list
" target="_blank">
https://salilab.org/mailman/listinfo/imp-dev




_______________________________________________
IMP-dev mailing list
" target="_blank">
https://salilab.org/mailman/listinfo/imp-dev




--
Barak


_______________________________________________
IMP-dev mailing list
" target="_blank">
https://salilab.org/mailman/listinfo/imp-dev


_______________________________________________
IMP-dev mailing list
" target="_blank">
https://salilab.org/mailman/listinfo/imp-dev




--
Barak