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 yannick@salilab.org 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 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. >>> >>> >>> On Mon, Aug 6, 2012 at 11:45 AM, Dave Barkan dbarkan@salilab.orgwrote: >>> >>>> >>>> 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 listIMP-dev@salilab.orghttps://salilab.org/mailman/listinfo/imp-dev >>>> >>>> >>>> >>>> _______________________________________________ >>>> IMP-dev mailing list >>>> IMP-dev@salilab.org >>>> https://salilab.org/mailman/listinfo/imp-dev >>>> >>>> >>> >> >> _______________________________________________ >> IMP-dev mailing list >> IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev >> >> > > > -- > Barak > > > _______________________________________________ > IMP-dev mailing listIMP-dev@salilab.orghttps://salilab.org/mailman/listinfo/imp-dev > > > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev > >