Similarly, I didn't realize that Barak's effort appears to have been semi-successful, in that people are working on it, since the last email he sent indicated that people didn't have time. Thanks to everyone for doing that. As usual, just being a P-I-T-A.
db
On 8/6/12 1:14 PM, Barak Raveh wrote: > p.s. I didn't mean to suggest that only the people listed below have > been helpful to IMP, and I bet if I add Dave, Ben, Javi, Max, Keren > and Charles to the list of past and present contributors, I am still > missing out on many people, I apologies in advance to anyone left > out!!! All I meant to say is that it's greaaaat many people think the > documentation effort is important, and that we're doing something > about it, so please come and join!!! > > Barak > > On Mon, Aug 6, 2012 at 12:40 PM, Barak Raveh <barak.raveh@gmail.com > mailto:barak.raveh@gmail.com> wrote: > > 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 > mailto: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 mailto: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.org mailto:dbarkan@salilab.org> 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 >> IMP-dev@salilab.org mailto:IMP-dev@salilab.org >> https://salilab.org/mailman/listinfo/imp-dev >> > > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org mailto:IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev > > > > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org mailto:IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev > > > > > -- > Barak > > > > > -- > Barak > > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev >