Page 1 of 1

NEURON Wiki?

Posted: Thu Mar 16, 2006 6:28 am
by ubartsch
Hi NEURON users,

As a NEURON beginner it is quite hard to find a solution to a specific problem either if I have a problem with writing hoc code or using the gui. I do know all the places to look at (programmers reference, NEURON site at Yale/Duke, NEURONDB, tutorials, manuals, NEURON Book), but as you can see by listing all these resources (and might have noticed yourself) it is a rather loose collection of information, partly outdated. (No offence intended here, I think developers are busy with other stuff!)

My idea was to start a Neuron Wiki. Most of the current knowledge base can be transerred simply by cut and paste and all users can easily contribute, which distributes the work effort (and most impotantly takes it away from the developers).

I would suggest to build templates for hoc classes and for gui entries, which have a similar scheme as the programmers reference (like: desscription, usage, example) but a little more detailed and where gui is always linked to underlying hoc codes.

Further I would suggest a slightly different organization of the Wiki than the programmers reference where info is orgnaized by topics. For instance I have organized bookmarks for the programmers references in folders like this:
NEURON GUI
...

NEURON HOC
General oc syntax
Basic math operations
Data types
I/O
Create mechanisms
Compilation of models
Integration
Single cell
Anatomically detailed models
Network
Graphics
mk gui's
Optimization/Fitting
Simulation management
This is only a personal favor, there is room for improvements and I think this should be discussed by all users.

But first of all let me know what you think about it. I think it would make life easier for a NEURON user, although we have to put a bit of effort in first!

It is just an idea, but if everybody contributes a little, it can be done!

Cheers
Ullrich

Posted: Thu Mar 16, 2006 8:16 pm
by hines
I'm definitely in favor.

Posted: Fri Mar 17, 2006 5:35 am
by Raj
Excellent initiative!

Posted: Fri Mar 17, 2006 12:17 pm
by ted
Properly done, this has the potential to be widely useful. Here are some practical
issues that come to mind.

Developing and maintaining documentation involves two related tasks:
creating content that answers users' questions
and
organizing it so that people can find it. Let's consider content first.

Content

For the purpose of this discussion, there are three kinds of content: One's level of expertise tends to influence the kind of content that one finds most helpful.

Experienced users can get along with "programmer's reference" content most of the
time. NEURON's Programmer's Reference could benefit from additional examples and
discussion. To this end, it would be helpful if there were a mechanism that made it easy
for users to add their own comments (see discussion about wikis below).

"How to" tutorials are generally most useful for users who are learning something new,
regardless of their expertise in other areas. There is a long list of tutorials that need to
be created. Anyone who wants to give it a try is more than welcome to do so; just pick
a topic you know something about, and have at it. Andrew Gillies and David Sterratt
wrote up a very nice tutorial http://www.anc.ed.ac.uk/school/neuron/ which is
widely read.

Unless I am mistaken, the resource that ubartsch is thinking about is primarily aimed
at documenting "best practices." This is where NEURON's biggest content gap on the
WWW. A bit is scattered in the FAQ list and tutorials on NEURON's WWW site, and
among this Forum's "Hot tips"
https://www.neuron.yale.edu/phpBB2/viewforum.php?f=28
We made a stab at including some "best practices" recommendations in The NEURON
Book, but much remains to be done.

Organizing content so that people can find it

Time is too short for me to say much about this right now, other than it's hard to do.
Think carefully before casting anything in stone. I wish I had a nickel for every time
it was necessary to revise the structure of the index for The NEURON Book.

Wiki or what else?

A purely technical issue: is wiki the right technology? Wiki has serious shortcomings.
For a current discussion, see "Why I don't like [edit: get] wikis" by Dave Taylor (page 56
of the April 2006 issue of Linux Journal, or read the article for free on his blog at
http://www.intuitive.com/blog/the_failure_of_wikis.html ). He concludes that "wikis are
going to end up in the good idea, bad implementation, or, perhaps, good concept,
bad fit with reality, graveyard."

Case in point: we have been thinking about migrating the online version of the
Programmer's Reference to a content management system that would allow any
registered user to add comments. The chief problem with using a wiki for this purpose
is the difficulty of maintaining the integrity of the "core documentation" itself, which
should be creatable and modifiable only by the NEURON development team. If anyone
knows of software that might suit our needs, please let me know.

WordPress, XML, or what?

Posted: Sun Mar 19, 2006 6:03 pm
by ted
Well, maybe a wiki is just fine for what ubartsch wants to do. My concern is with
NEURON's core documentation.

Blogging may have an edge over wiki as a mechanism for the collaborative development
and presentation of core documentation. One interesting package is WordPress
http://wordpress.org/. What makes WordPress particularly relevant to core
documentation is its granularity of access control. That is, WordPress seems capable
of granting members of a "development team" create/edit access to what they call
"main content" (which would consist of the core documentation) while also allowing
comments from any registered user. I wonder if any NEURON users have used
WordPress, or similar programs, and might be able to add their two bits to this
discussion.

Or should we just turn all of the core documentation into XML and manage it with php?
For example, see the php manual http://www.php.net/manual/en/, which does an
excellent job of organization and (protected) presentation, while also allowing
comments.

An aside: maybe it makes sense to split this discussion into two threads--
one about the project that ubartsch has in mind, and the other for discussion about
what to do with the core documentation.

NEURON Wiki!

Posted: Wed Mar 29, 2006 10:08 am
by ubartsch
Hi,

I personally would go along with detlefvonberg who pointed out that Wiki is both flexible enough to let users easily contribute to the knowledge base but has mechanisms to protect final versions of content from being modified.

Further on I was not thinking of "just another" place to look for information (only best practises). I think the Wiki should incorporate all available information on NEURON, organise it in a logical way (what that is needs to be determined, though) and link together all levels of "sophistication".
A newbie doesnt transform into an experienced user all of a sudden, it's a smooth transition.
And sometimes a newbie rather wants to know how to write hoc because he has programmed many other languages - or a guy who only did huge IF networks wants to try to work on an reconstructed morphology by using the cell builder and maybe later wants to know what the hoc behind the cell builder really does.

I think there should be one central repository for NEURON knowlegde.

If I look up how the cellbuilder works for the first time, I will be fine with an explanation of the buttons and their functions. If I look up the cellbuilder for the 50th time I might want to know how to write similar code to run my simulations in an automated fashion. Certainly the first place I will have a look at, is the place I have visited the past 50 times!

And that is one of the main strength of Wiki: interlink different levels of knowlegde in a common framework!

So let's build the one place, apart from the forum maybe, where people look up information on NEURON. Let's put all the programming references, tutorials, howtos, best practises and whatever else in the Wiki and make it a little easier and most importantly quicker to find information!

Just an opinion...

Cheers
Ullrich

Re: NEURON Wiki!

Posted: Wed Mar 29, 2006 11:50 am
by ted
ubartsch wrote:I think there should be one central repository for NEURON knowlegde.
Depends on the meaning of "one central repository." One thing it should not mean:
stuffing everything into a wiki. wiki has obvious strengths for certain kinds of
documentation, but it also has undeniable weaknesses that preclude it from being
"the right tool for all documentation." Is there even one example of a programming
language project that has wrapped up all of its documentation into a wiki? php doesn't
use wiki for its documentation. Neither does perl, Python or Ruby. The developers who
work on those projects are pretty smart cookies. If wiki is so great, why haven't they
jumped on the bandwagon?

The right tool for the right job, as the saying goes.

Re: NEURON Wiki?

Posted: Mon May 23, 2011 9:43 am
by ted
The spammer who added a junk post* to this thread has been deleted, along with his/her/its post. But the general idea is still a good one. Please note that events over the past 5 years have somewhat overtaken the discussion. For the past few years, NEURON's WWW site http://www.neuron.yale.edu/ has been implemented with a content management system that allows access for comments and discussion to registered users, and contributions from authorized users that range from short technical notes to extensive tutorials and documentation of specific topics. NEURON users who are knowledgable and interested in participating in improving and expanding http://www.neuron.yale.edu/ should either post a message on the NEURON Forum or enter a comment at http://www.neuron.yale.edu/.

*--The post included a gratuitous link to an unrelated commercial WWW site.