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.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 >>> >>> >> > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev > >