Slashdot Mirror
Corporate Software Development Wiki?
gnujoshua asks: "My company would like to expand the use of its Wiki to include source code and API documentation. It would be nice to have auto-generated, syntax highlighted, and well documented source code, integrated nicely into the Wiki. Ideally, changes to source could be made right in the Wiki, barring permissions, and furthermore, it would be nice to see if it compiles against the library as well. What recommendations does Slashdot have for Wikis and scripts that could be used effectively to this end?"
Nothing is impossible with enough perl scripts!
Or at least the (pick one) CVS, SourceSafe, or Sourceforge? Why must it be Wiki when there is a perfectly good ecosystem of software that ALREADY DOES THIS JOB?!?!?!?
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
I'd recommend starting with a generic Wiki (MediaWiki?), and then editing it to suit your purposes.
I'll subscribe to Slashdot when I see a month without a dupe, a typo, or an article the "editors" didn't read.
Nothing is impossible with enough perl scripts!
The syntax.... it haunts me....
May the Maths Be with you!
Whom the gods would destroy, first they teach perl.
nDoc 1.3.1 has an XML output option. With a bit of work that could be used to populate a Wiki style website. I use nDoc with VS.Net 2002 and 2003, and I believe there is a beta version for working with VS.Net 2005. I'm not sure what other languages it support.
-Rick
"Most people in the U.S. wouldn't know they live in a tyrannical state if it walked up and grabbed their junk." - MyFirs
Interesting idea to integrate a Wiki with a version-control browser. I wouldn't want to use a Wiki as my editor however.
TWiki uses RCS as its backend. Thus if you use CVS for version control (which is based on RCS), modifying the Perl-based TWiki to talk with your CVS repository should be feasible.
Our motto is, "The software company with source code that anyone can edit".
Trac: "Trac is an enhanced wiki and issue tracking system for software development projects."
Karma: -2147483648 (Mostly affected by integer overflow)
And POD...
You know, I recommend Google. For instance it took me less than a minute searching on Google to find this http://qbnz.com/highlighter/. It's called GeSHi, and, apparently, it is an open source library for generic syntax highlighting. Maybe you could put just a little bit of effort into looking for a solution before you try to get a community of thousands to spend their time doing it for you. A good first step would be to find your own answer to the other few problems you mentioned now that I've given you one for free.
-GameMaster
Rules of Conduct:
#1 - The DM is always right.
#2 - If the DM is wrong, see rule #1
This is your boss, get back to working!
What's the point, exactly? Why would you want to make a very valuable assett editable by anybody? This seems like a HUGE step backwards from having some kind of source control.
I don't respond to AC's.
We run CVS for code, and I have TWiki set up (to experiment with collaboration on an internal wikipedia for engineering discussion). I'm thinking the easiest is to install a CVS Apache web interface (there's at least one I've used before) so that the TWiki entries could at least reference the CVS web pages if desired.
I agree with other posts that using twiki to directly edit source code doesn't sound like a good idea..
Bavarian Purity Law of Rice Krispie Squares: Rice Krispies, Marshmallows, Butter, Vanilla.
And they just released a nice shiny version 4.0.0 of TWiki, which I can't wait to try out.
you had me at #!
Sounds like a job for Trac. http://www.edgewall.com/trac . Subversion + wiki + bug tracking.
Dokuwiki has a those features already. It's not a behemoth like MediaWiki, but it does a pretty good job. It's intention is to allow developers to document their work without having excessive overhead.
Preface: Yes, I know they're not open source. Guess what? I don't care! It's great software!
I highly reccomend Confluence as a Wiki for software development. Aside from being just about the perfect Wiki for any purpose, it's got great syntax highlighting and plugins for development. Not sure if it would let you edit directly from the web, but seriously, reconsider that requirement. I doubt anyone would actually use that anyway. It does have JUnit test reports built in too, so it's even better if you're using Java. It also integrates tightly with their bugtracking software JIRA, which is also amazing if you don't have a good bugtracker yet. But even if you're just using confluence for docs and specs, it's definitely the best Wiki out there for that.
Other than that, there's always everything else ^^^ that has already been said... Good luck!
"!"
Use SVN and then use TRAC.
IT's a wiki!
It's a source browser (with color highlighting)
It's a ticket tracking system (can import bugzilla, or be turned off)
It's a floor wax!
It's a dessert topping
(well, not the last two).
But it's pretty awesome, INSANELY easy to set up, and pretty slick/easy to use.
He does not want to store all of his code in the wiki.
He wants to set it up so that when a programmer CREATES a wikipage on a function, he can include source code FOR A SAMPLE INVOCATION of the function and have that code be nicely formatted, syntax-highlighted and so on without the programmer having to to do it all by hand.
In other words:
Now, I am sure that he wouldn't mind it if there were some form of Doxygen-style "Code goes in here, and initial versions of wikipages come out here" interface, so that you could start from the Doxygen generated pages and then annotate them better.
OK, folks? Got it?
Good.
Now, comment.
www.eFax.com are spammers
if your language/setup of choice already has a repository browser, syntax highlighter and/or javadoc equiv., just link to them from the wiki. we use mediawiki at work, and link to the javadocs, CVSWeb, StatCVS, the Bugzilla report engine, etc.
(btw, editing your project's source code from a web form for anything but the most trivial projects is a dumb idea. this is why we have IDEs and version control systems)
http://kered.org
http://www.edgewall.com/trac/
From the "What is Trac" page:
* An integrated system for managing software projects
* An enhanced wiki
* A flexible web-based issue tracker
* An interface to the Subversion revision control system
Seems like that would work well for your purposes. I'm not sure if it does syntax highlighting, but it wouldn't be too hard to add that functionality.
IMHO this sounds like a terrible idea. Are you going to try and get your developers to write their code inside the mozilla text edit box? It's much harder than using vi/emacs/textpad/MyFavEditor.
Wouldn't it be much better to have your wiki link to something like ViewVC so you can see what the current code looks like.
If this is because you're having trouble getting your developers to comment their code, it's not going to make it easier by commenting in Wiki.
Anyway I'm a firm believer in documenting the reason for code, not the working of the code. If you can read code, the working is right there in front of you, but you may not know WHY something was done.
Anything is possible, except skiing through revolving doors.
Software like mediawiki can be controlled so that if you're not logged in, you can't see or edit any pages. By flipping a true/false option, you can prevent anonymous users from registering, and apache contains Directory lines to only allow certain IPs, users, groups, etc. If you dedicate a few minutes, mediawiki actually makes a pretty good internal documentation tool - and not just documenting source code.
Long before Trac for Subversion, there was CVSTrac for CVS. It's a little more austere, but offers the same features: integrated wiki, CVS change tracker, CVS browser, and trouble tickets. CVSTrac now can be compiled to support Subversion.
FitNesse combines a Wiki with an acceptance testing tool. Tables on Wiki pages hold test data and expected outputs; click the "test" button and FitNesse runs your application with the test data and checks the results against the expected values (similar to JUnit and others). Although written in Java, FitNesse also can test Python, Ruby, C++, .NET, Smalltalk, and Perl applications. FitNesse builds on Fit, the Framework for Integrated Testing by Ward Cunningham, the creator of the original Wiki.
Ward also was the first person to integrate source code into a Wiki. In his WikiBase , Ward presents the source code for his original Wiki on Wiki pages containing HyperPerl, a Perl implementation of Literate Programming. This may not suit current development needs, but it is fascinating.
Version control is not just for programmers.
Which is why MediaWiki, in use by countless people through the website en.wikipedia.org, supports version control for all articles.
I contracted at a company where we looked into doing what you have suggested in the context of a BI team. Basically, using a wiki to submit code changes is a candidate for the Too Hard basket.
Instead, what we did was write a bunch of services that interrogated our various source code repositories (database schema, stored procs, code, cube specifications etc) and generate a page for every object we were interested in with links to related objects.
Each page will contained autogenerated documentation (formatted to look nice etc) as well as user comments. The autogenerated data was refreshed every night, but the user comments were able to persist.
Make it all searchable and you have a very usable wiki that allows users to get a handle on how things hang together.
Forget about using a wiki to submit changes to the SCC system. Nightmare !
It's good luck to be superstitious
Some positive aspects
Some negative aspects
To summarize, the editor bugginess is what irritates me the most. If they (Atlassian) can fix the editor, then Confluence will be very interesting indeed.
Sources are available to commercial licence only ... but it's available. Looks like OpenSource to me. Maybe they should not give non-commercial licenses ?
http://www.atlassian.com/software/confluence/Con fluenceSourceDownloads.jspa
AWx
Sig (appended to the end of comments you post, 120 chars)
we use trac with Subversion and generate documentation automatically with JavaDoc and phpDoc.
Seriously, anyone who creates writing that changes over time would benefit by using a version control repository.
Just look at the history feature of Wikipedia. It's arguably one of the most important features of the encyclopedia.
If Microsoft Word used a version control repository, a vast majority of business tragedies would be ameliorated.
How's that for a bold statement.
My father is a blogger.
Trac is a web-based software project management and bug/issue tracking system. It provides an interface to Subversion and an integrated wiki. It uses Apache and mod_python, but it's really easy to install if you follow the instructions.
You can see examples of it in use at PylonsHQ and the Django site, both of which are styled nicely. You can see a default install at PyDelicious.
And no, it's not only Python sites that use it. Those are just the ones off the top of my head. :)
-- null
I haven't seen SourceSafe corrupt a repository since Version 4. Version 6 seems to be quite stable in that respect. But I agree with the rest.
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
Let's say a developer someone left out an "@see" in their code so the Doxygen didn't create a nice hyperlink as it could have. Well, in some cases, it might be nice for the documentation person to immediately make this change rather than checking it out. Let's say, perhaps, that if a minor change is made by user DaveDocumentor to a wiki page of type SourceCode, that the developers are sent an email with the diff so that they can make the change ot the CVS repository. This would speed up the time it takes for proper documentation to be created, while also creating a nice form of communications. A Diff of appropriate format is alway sent to the appropriate person and the minor change was made immediately to the documentation. Assuming the person who gets the diff goes ahead and makes the change to the CVS tree eventually, it won't be a problem. But, having yet another person checking out files in the CVS tree can be more of a haltle than it is worth. There could be a smaller margin of error in the scheme I presented. Or, maybe not. But, it is somethign worth considering.