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.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 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 >> >> >