Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Document Management and Version Control?

Cliff posted more than 8 years ago | from the need-not-be-mutually-exclusive dept.

326

Tom wonders: "I am working in a medium-sized software development company. The functional analysts use Microsoft Word to document the specifications, and Sharepoint to publish the documents. However we'd like to improve our process to have better revision control and traceability. We have looked at alternatives like using Wikis, or static HTML documents with CVS. The functional analysts want ease of use, while we developers would like to see high-quality end products, revision control (i.e. tagging & branching of the document base), and traceability features. What tools and document formats do you use and would recommend?"

cancel ×

326 comments

Sorry! There are no comments related to the filter you selected.

I'd have to say... (3, Funny)

drakaan (688386) | more than 8 years ago | (#15475508)

Shoot the functional analysts. Once that's done, there won't be any complaining, and you can use CVS. Extreme, but simple.

I'd have to say...go out with a bang. (0)

Anonymous Coward | more than 8 years ago | (#15475922)

"Shoot the functional analysts. Once that's done, there won't be any complaining, and you can use CVS. Extreme, but simple."

So how many have you shot?

Re:I'd have to say... (1, Funny)

Anonymous Coward | more than 8 years ago | (#15476120)

Shoot the functional analysts. Once that's done, there won't be any complaining, and you can use CVS. Extreme, but simple.

After that, shoot the CVS zealots.

The simple answer (5, Informative)

Ckwop (707653) | more than 8 years ago | (#15475515)

Latex with CVS. This is what I use for my documents. It's simple (yes it is simple.. markup languages are not hard to understand) and with CVS it's far more feature complete than Word in version control.

There's plenty of WYSIWYG tools for Latex. Let Google be your guide.

Simon.

Re:The simple answer (5, Informative)

CRCulver (715279) | more than 8 years ago | (#15475622)

There's plenty of WYSIWYG tools for Latex.

I'm always happy to see fellow TeX evangelists here. If you don't know about LaTeX yet, check out the TeX Frequently Asked Questions [tex.ac.uk] and discover the joys of a typesetting system that is not only high-quality, but free as in freedom and immensely extendable.

LaTeX's markup makes so much sense that a WYSIWYG tool isn't necessary, for even the man on the street can be just a productive with doing it up in a text editor. A good and free as in beer guide to the system is The Not So Short Introduction to LaTeX2e [ctan.org] , though if you are going to be markup up lots of math (LaTeX's specialty) you'll probably want Graetzer's Math Into LaTeX [amazon.com] since LShort doesn't cover it so much.

Re:The simple answer (2, Funny)

Doc Ruby (173196) | more than 8 years ago | (#15475662)

TeX can be very productive as long as people don't waste any of your time talking about pronouncing "Tex" as "techh" (*clears throat*).

Just like Linux productivity jumped when people stopped wasting any time talking about pronouncing it "lihnuhks" vs "lienuhks".

Re:The simple answer (2, Insightful)

fm6 (162816) | more than 8 years ago | (#15475714)

LaTex may be terminally cool for creating fancy-looking documents. But it doesn't solve any problems that this guy cares about. For his purposes, it's just another word processing format.

Re:The simple answer (4, Informative)

Ithika (703697) | more than 8 years ago | (#15475817)

LaTex may be terminally cool for creating fancy-looking documents. But it doesn't solve any problems that this guy cares about. For his purposes, it's just another word processing format.

Not true. The OP asks about version control and branching... and the best way to store something for version control is as plain text. Yes, modern version control software allows fairly sophisticated binary deltas (for example, I believe SVN has this capability) but there are still features that can't be done without text.

For example, can your version control software tell you what text changed between two revisions of Word documents? It can if they're LaTeX documents.

Re:The simple answer (1)

fm6 (162816) | more than 8 years ago | (#15476025)

Plain text makes it easier to manage version control and branching. But it's not enough. You need a simple document structure that doesn't embed a lot of formatting crap in your document.

And even if you're right, you don't need to switch to LaTex to have plain text files. All word processors, including Word [wikipedia.org] , have plain text formats.

Re:The simple answer (1)

Ithika (703697) | more than 8 years ago | (#15476134)

You need a simple document structure that doesn't embed a lot of formatting crap in your document.

That is a reason to use LaTeX or similar markup scheme which promotes separation of content from styling. I don't know much about DocBook, so it may be an even better candidate for that sort of thing.

Using RTF from may be feasible, but from what I remember its RTF output is just as ugly as its HTML. It would be horrible to use with diff.

Re:The simple answer (1)

fm6 (162816) | more than 8 years ago | (#15476200)

I agree that separation of content from presentation is a good idea. Indeed, for thie purpose at hand, it's essential. But LaTeX does not do any such thing. It embeds formatting info in the document.

Re:The simple answer (3, Informative)

masklinn (823351) | more than 8 years ago | (#15476309)

Uh, no, latex embeds semantics into the document, then uses classes & packages to translate these semantics to visual displays.

Re:The simple answer (1)

dorkygeek (898295) | more than 8 years ago | (#15476316)

Very true! That's why I encourage people to look at DocBook [oasis-open.org] . I've been using it for over a year now in lieu of LaTeX for documents ranging from simple HowTos, to design and specification documents, and some nearly book sized projects.

Paired with a sensible XML editor, you can be very productive!

Re:The simple answer (1)

commonchaos (309500) | more than 8 years ago | (#15476330)

What editor do you use?

Re:The simple answer (0)

Anonymous Coward | more than 8 years ago | (#15476177)


And even if you're right, you don't need to switch to LaTex to have plain text files. All word processors, including Word, have plain text formats.


Oh how I wish. I dunno. Maybe it works now, but back a few years ago when I was working on a project that actually tried to do this, we got torpedoed by MS Word spitting out lines that were longer than 256 characters (which broke the SCM we were using)

Re:The simple answer (1)

Branko (806086) | more than 8 years ago | (#15476270)

For example, can your version control software tell you what text changed between two revisions of Word documents?

No, but Word itself can. Use "Tools / Compare and Merge Documents" (in Word 2003).

Re:The simple answer (4, Informative)

flooey (695860) | more than 8 years ago | (#15475826)

LaTex may be terminally cool for creating fancy-looking documents. But it doesn't solve any problems that this guy cares about. For his purposes, it's just another word processing format.

Actually, switching to LaTeX changes the scope of the problem from tracking changes to arbitrary files to tracking changes to text files. There are a lot more tools that are good for the latter problem than the former, so the available options get bigger. You're right that it doesn't suggest a good tool to go with, though.

Re:The simple answer (1, Insightful)

fm6 (162816) | more than 8 years ago | (#15476063)

See my response to somebody else [slashdot.org] who said pretty much the same thing you did.

Re:The simple answer (4, Insightful)

dsandler (224364) | more than 8 years ago | (#15475742)

LaTeX's markup makes so much sense that a WYSIWYG tool isn't necessary, for even the man on the street can be just a productive with doing it up in a text editor.

I love LaTeX (I have TeXShop [uoregon.edu] open in the background right now!), but I have to argue with the assertion that the uninitiated "man [or woman! -ed] on the street" can be just as productive as s/he was in Word. Compare Word's graphical table builder and tab ruler, the result of about 20 years of noodling around with the best user experience for creating such things, with \begin{tabular}{|r|r@{.}l|}. OW MY WORD PROCESSOR.

Even if you give everyone a pocket syntax reference, unless you have a TeX ninja working overtime on your templates, you'll still end up with a lot of documents that look like academic research papers. This is fine if what you're writing are academic research papers [hi!], but for most corporate communication people are accustomed to more effortless (read: WYSIWYG) control over the output. (This is, of course, usually a terrible idea, resulting in official RIF memos from HR written in Comic Sans; I think there's a happy medium somewhere in between.)

Re:The simple answer (1)

CRCulver (715279) | more than 8 years ago | (#15475781)

When did I saw that the person would be just as productive as in Word? LaTeX and Word are in entirely different classes of software. One's a typesetting system, the other's a word processor. For the man on the street who needs to formally typeset something, LaTeX is the best option since it's high-quality and free (in both ways).

Re:The simple answer (2, Interesting)

dsandler (224364) | more than 8 years ago | (#15475887)

When did I saw that the person would be just as productive as in Word?

Sorry, I over-generalized "WYSIWYG tool [for LaTeX]" to WYSIWYG document processor. You're probably right that graphical LaTeX editors aren't substantially more accessible than the bare LaTeX markup.

[Aside: Where are these men-on-the-street who need all this professional typesetting? I want to live on that street! My car probably wouldn't get broken into as much.]

Re:The simple answer (1)

fm6 (162816) | more than 8 years ago | (#15476227)

When did I saw that the person would be just as productive as in Word?
You said "a WYSIWYG tool is unnecessary". Perhaps you forgot to add "if you don't give a shit about productivity."

Re:The simple answer (1)

Anonymous Brave Guy (457657) | more than 8 years ago | (#15476301)

That's a matter of perspective. Using Word, you couldn't produce the kind of LaTeX'd documents I've seen in fields from mathematics and software engineering to linguistics, no matter how long you tried. And for that matter, someone competent with a tool like LaTeX will generally be far more productive doing a task that suits it than someone competent using a tool like Word.

As I've commented here several times before, it's a mystery to me why no-one has got wise to this and filled the rather large gap between Word (pretty UI to some people, but seriously underpowered for non-trivial work) and LaTeX (seriously powerful if you know what you're doing, but some daft limitations and horrible usability). It's not like the basic concepts underlying both Word and LaTeX have been around for more than a decade or anything...

Re:The simple answer (1)

deepestblue (206649) | more than 8 years ago | (#15475930)

While the rest of the world has gone ahead, (La)TeX is still in stuck in 7-bit ASCII land and is thus unusable for the languages I have documents in. And no, Omega/Lambda is still vapourware.

Re:The simple answer (3, Informative)

CRCulver (715279) | more than 8 years ago | (#15475972)

This is totally false. All modern LaTeX installations allow one to typeset text in UTF-8. As a student of comparative Indo-European linguistics, I regularly typeset documents mixing the Greek, Cyrillic (including obscure OCS characters), and Latin scripts, as well as the International Phonetic Alphabet. I've also typeset some simple things in simplified Chinese.

Re:The simple answer (1)

deepestblue (206649) | more than 8 years ago | (#15476041)

How did you know what languages I had in mind? I was talking about Tamil or Devanagari. Current solutions don't handle ligatures very well, if at all.

Actually, I find (La)TeX sub-par even for accented Latin (as used in IAST, for example). I don't want to have to treat combining characters differently from regular Latin.

Re:The simple answer (2, Insightful)

CRCulver (715279) | more than 8 years ago | (#15476157)

Most UTF-8 software doesn't handle Devanagari well. LaTeX is hardly in the stone age compared to other programs.

Actually, I find (La)TeX sub-par even for accented Latin (as used in IAST, for example). I don't want to have to treat combining characters differently from regular Latin.

Accented Latin doesn't require combining characters, since macron-ed vowels are distinct characters in Unicode. When I write a LaTeX document with Latin, I enter all characters in just plain, direct UTF-8.

Re:The simple answer (1)

CRCulver (715279) | more than 8 years ago | (#15476178)

Incidentally, it is possible to typeset very elegant Devanagari with LaTeX. Charles Wilker's A Practical Sanskrit Introductory [sanskrit.gde.to] was typeset in TeX. See his explanation [sanskrit.gde.to] for more details. While Devanagari cannot be entered as straightforwardly as most other scripts, it can still be typeset.

Re:The simple answer (2, Informative)

CRCulver (715279) | more than 8 years ago | (#15476002)

I should add that it's usually a simple matter of adding
\usepackage[utf8]{inputenc}
to the document preamble. For hyphenation, you also need to do
\usepackage[x,y...]{babel}
where x where the arguments are whatever languages you want. Today I wrote a letter to a friend where my document preamble had
\usepackage[polutonikogreek,danish,french,latin,ro manian,british]{babel}
And you tell me LaTeX can't handle the languages of the world?

MOD PARENT FUNNY (0)

Anonymous Coward | more than 8 years ago | (#15475678)

This guy is hilariously absurd.

Just imagine telling people who "style" their 50-page Word-document by manually formatting every heading instead of defining and using styles how to use LaTeX.

dev> So, you just open a tex-file in a text editor...
cunt> Like Word?
dev> No, you see, Word is a word processor. You have to use Notepad.
cunt> But Notepad has no formatting-toolbar.
dev> I said you have to use Notepad
cunt> But...
dev> M$ sux0r omg open sores
cunt> (blank stare) Well, whatever you say, Sir. (slowly backs off and phones the security staff)

Re:MOD PARENT FUNNY (1)

CRCulver (715279) | more than 8 years ago | (#15475724)

People who have to word-process are in a different demographic from those who typeset. LaTeX is not a substitute for Word. I'd recommend LaTeX to typesetters, regardless of skill level, because it works so well, and there's really no higher-quality solution to be had.

Re:MOD PARENT FUNNY (0)

Anonymous Coward | more than 8 years ago | (#15475870)

Hey, don't interrupt our sophomoric circlejerk with your realistic anecdotes!

Re:The simple answer (1)

jrockway (229604) | more than 8 years ago | (#15475710)

> There's plenty of WYSIWYG tools for Latex. Let Google be your guide.

GNU TeXmacs is one that I've recently discovered, and it's quite nice. It's especially good if you want to incorporate sessions with programs like gnuplot, octave, or guile into your documents. (For example, if you type "plot x**2" while in gnuplot mode, the graph produced becomes part of your document, just like in Mathematica.)

It's also good for your other daily typesetting needs.

Re:The simple answer (1)

bheer (633842) | more than 8 years ago | (#15475775)

If you don't have existing repositories, subversion might be a better choice than CVS. In fact, subversion's binary delta storage can make it trivial to store Word docs or any other binary file in a SCM system.

This has the added benefit of achieving the poster's goal of record-keeping with minimum disruption to everyone's way of working.

Re:The simple answer (2, Insightful)

Karma Farmer (595141) | more than 8 years ago | (#15475811)

There's plenty of WYSIWYG tools for Latex

No, there aren't. If you believe a WYSIWYG tool is possible for LaTeX, then you either don't understand LaTeX or you don't don't understand WYSIWYG.

Re:The simple answer (1)

peej73 (951609) | more than 8 years ago | (#15476144)

Maybe use SVN rather than CVS - it does all the same stuff but version directories too... this makes it much less of a big decision about when to start the version control, so you start earlier, and it's smiles all around. TortoiseSVN is a winblows client which works really well and I've even found managers who can understand it.

Re:The simple answer (0)

Anonymous Coward | more than 8 years ago | (#15476153)

and with CVS it's far more feature complete than Word in version control.

CVS is far from being a decent reversion control these days, however. Things like git, hg or svn will make your life more easier...

Subversion... (4, Informative)

nweaver (113078) | more than 8 years ago | (#15475516)

Subversion is your friend...

It handles binaries right (unlike CVS)

It works over a variety of transport layers (HTTP/HTTPS/SSH) with some decent authentication models.

It treast revisions as an archive-wide property.

You can't check in an inconsistant state.

It runs under *NIX, Mac, Windows, etc.

Its free software.

Try it. I switched a few months back from CVS and have been very happy.

Re:Subversion... (1)

jokerr (618070) | more than 8 years ago | (#15475583)

What about a n00b friendly UI? I'm working on setting up a SVN server for my office but I know that if the end users have to do more than a few clicks/keystrokes they won't use it. Let's just say that a majority of the people that I work with are totaly PEBCAK prone.

Re:Subversion... (2, Informative)

BigCheese (47608) | more than 8 years ago | (#15475620)

If you're in Windows try TortiseSVN . It's a Explorer plugin and makes Subversion very easy to use.

Re:Subversion... (2, Informative)

delirium28 (641609) | more than 8 years ago | (#15475627)

Check out:

SmartSVN [syntevo.com]

Back when I was looking at SVN clients, I found this one had the most promise. Of course, if you have users who know Windows Explorer (assuming your site is MS-based), then TortiseSVN [tigris.org] is another good alternative.

Re:Subversion... (3, Informative)

Tordek (863609) | more than 8 years ago | (#15475656)

Make them read this http://svnbook.red-bean.com/ [red-bean.com]

Wait, scratch that... FORCE them to read it...

I've been using it (okay, I'm not in any Big Projects as we speak, but i've tried it), and it can be mostly simplified to svn update && svn commit for most of the time...

Re:Subversion... (2, Insightful)

masklinn (823351) | more than 8 years ago | (#15476342)

TortoiseSVN. Seriously, try it, it's extremely good, fairly stable, and features a high integration to Windows Explorer (with nice icons to boot) which means that your user don't have to learn a whole new software: they're working in a familiar environement with just some more items in their contextual menu.

Re:Subversion... (1)

Homology (639438) | more than 8 years ago | (#15475759)

Subversion is your friend...

It handles binaries right (unlike CVS)

Of course, Subversion is no more your friend than CVS in this case since neither can do proper diffs! It's binary data for f*ck sake! Subversion handles binaries better than CVS, but not for the reason you state.

Re:Subversion...[*Does* Call Binary Diff Tools] (5, Informative)

malloc (30902) | more than 8 years ago | (#15476121)

Of course, Subversion is no more your friend than CVS in this case since neither can do proper diffs! It's binary data for f*ck sake! Subversion handles binaries better than CVS, but not for the reason you state.

Actually, GUI Subversion clients like TortoiseSVN [tigris.org] can show diffs for binary files like Word or OpenOffice, using the built-in diff capability of these programs. The end result is you can double-click your binary document and get a window showing you the differences.

The latest nightly TortoiseSVN builds even include an image diff viewer.

-Malloc

Re:Subversion...[*Does* Call Binary Diff Tools] (1, Interesting)

Homology (639438) | more than 8 years ago | (#15476208)

Actually, GUI Subversion clients like TortoiseSVN can show diffs for binary files like Word or OpenOffice, using the built-in diff capability of these programs. The end result is you can double-click your binary document and get a window showing you the differences.

Thanks, this is great news.

Re:Subversion... (1)

ArchAngelQ (35053) | more than 8 years ago | (#15475807)

Don't forget TortoiseSVN [tigris.org] , for more ease of use for the windows people.

Re:Subversion... (2, Insightful)

MichaelSmith (789609) | more than 8 years ago | (#15475840)

Subversion is your friend...

I have been moved on to a new project to develop a user interface in Java. I have java development skills but my job is to write UI specs in word and visio. The developers use SVN for their code and somebody checked the documentation tree (where I and three other engineers work) into SVN.

But the people I work with (systems engineers, in our terminology) rely entirely on windows explorer and email to manage their documents. They have a complex file naming scheme which is always breaking. They have to manually sync with one off site engineer by email. Word locks documents for read/write if it can so you have to ask people to release documents for your control.

I have suggested several times using SVN to manage documents but none of my fellow workers will have a bar of it.

I am not a fan of SVN myself, I prefer totally distributed systems, but in this case it would be the right tool to use.

Re:Subversion... (1)

CharlieHedlin (102121) | more than 8 years ago | (#15476278)

Tortoise SVN would be your friend. It allows you to easily use SVN from windows explorer.

Re:Subversion... (1)

masklinn (823351) | more than 8 years ago | (#15476357)

I suggest you start by committing everything into SVN and using it for yourself (like commit other people's changes as "misc other people changes" and then commit your own changes with real commit messages), if only to prevent you from being annoyed by the issues it brings.

Then you can start evangelizing.

Re:Subversion... (1)

JPyObjC Dude (772176) | more than 8 years ago | (#15476179)

Thanks. You saved me the typing.

I support this completely ... Subversion rocks :]

Also, when you run a diff on an M$Word document, it acually loads a MSWord Diff version so you can graphically see the differences in the document. Not sure if OOo has this yet...

JsD

Re:Subversion... (0)

Anonymous Coward | more than 8 years ago | (#15476300)

I've used cvs for years. I've been forced to use LiveLink for years (since they say that's a DOCUMENT configuration management system). I've played with plone, VisualSourceSafe, Sharepoint and evaluated others. SVN is the best I've seen and love using it everyday. Yes, there is the main concept of VM you have to teach non SW types, but it is totally worth it.

From your requirements, tracability, publishing to peers, & process; I would highly suggest adding trac from http://www.edgewall.com/trac/ to your svn setup. It encapsulates svn into a nice package of wiki, ticket tracking, process flow, as well as content presentation.

Re:Subversion... (1)

ari_j (90255) | more than 8 years ago | (#15476314)

My problem with svn as opposed to cvs is that sometimes I want to have per-file revision tracking. For instance, my directory full of miscellaneous documents is such a place. I do not care what the relative state of the documents is at any given point, because they have no interrelations whatsoever. Source code and independent documents are different animals, and I don't know of a revision control system that treats both of them the right way.

Re:Subversion... (0)

Anonymous Coward | more than 8 years ago | (#15476352)

If Subversion is merely your friend, then Mercurial is your humble servant.  It is the Alfred to your Bruce Wayne.  Subversion is painful by comparison (in terms of merging and in other ways).  Try it and you won't look back (except maybe to migrate your Subversion repository over to Hg).  It's *damn* fast, it provides much of what you'll find in the BitKeeper interface, and creating extensions for it in Python is a trivial task.  It is the future.

Re:Subversion... (1)

KronicD (568558) | more than 8 years ago | (#15476358)

Yep, it sounds like subversion + trac is the way to go! :)

ODF + SVN (1)

jokerr (618070) | more than 8 years ago | (#15475525)

Is there any way to migrate to the Open Document Format and then store everything under SVN? OO writes/reads Word files so it might be possible to read the files and save them in the open format. I'm not too familiar with the inner workings of SVN but I know that it r0x0rs for ascii files. I haven't researched SVN support for bin/doc/compiled files.

ODF + NSA (0)

Anonymous Coward | more than 8 years ago | (#15475640)

I used to worry about this, but these days I find it's easier and more reliable to place our records in an open format and store then on a networked plaintext fileserver. You don't have to worry so much about user-end changes; just make sure there's some standard CALEA entry point and the relevant authorities will manage all version changes and backups without any additional effort on your part.

Re:ODF + SVN: auto unzip and rezip? (3, Interesting)

Noksagt (69097) | more than 8 years ago | (#15475837)

ODF files are just zip files which contain the content in an XML file with supporting text and binary files. The text files are auto-generated & so may have "weird diffs" particularly when multiple people/programs/platforms work on them. I have an ical server backed by subversion's webdav & the diffs are always very amusing, as each program changes whitespace & other such nonsense.

The diffs might still be more usable than those for a 100% binary (zipped) file, particularly for single-user situations.

Has anyone played with compressing/decompressing ODFs for use with version control software? Any pointers?

Question I ask my coworkers too (2, Informative)

lymond01 (314120) | more than 8 years ago | (#15475530)

Someone replied: "Ever heard of Adobe Acrobat? That's what it's for." I'd like to say they missed the point of the question, which isn't just edits to a document. What I think the poster, and myself, are searching for is a web-based document server that tracks who's working on what, when. So if I decide I'm going to work on the Abstract of a paper, I go online, download it, and work on it. Let Word or whatever track my exact edits.

When another user decides to edit it, they'll see that it's "checked out" and that they should work on something else, or contact me to continue with my edits. This avoids people working on the same document. Version control. It doesn't have to be complex to the end user, but I think the behind-the-scenes work for tracking uploads and downloads, different document piles, etc, would be extensive.

Re:Question I ask my coworkers too (2, Informative)

Anonymous Coward | more than 8 years ago | (#15475665)

SugarCRM's document feature does exactly that (web-based check-in/check-out). Plus, it's open source (yay) and does a bunch of other stuff, which you may or may not need (I believe you can just turn off other modules/functions that you don't need so that they don't bother you).

http://www.sugarcrm.com/ [sugarcrm.com]

Re:Question I ask my coworkers too (0)

Anonymous Coward | more than 8 years ago | (#15475863)

"SugarCRM's document feature does exactly that "

It's a glorified address book, you astroturfing fucktard.

SugarCVS?? (0)

Anonymous Coward | more than 8 years ago | (#15476238)

Mmmmm... SugarCRM is a great, say it with me, "Customer Relationship Management" open source app... However, it is not CVS.

I will now attempt translate this concept for the upper echelon:

CRM != CVS

Re:Question I ask my coworkers too (2, Informative)

Truman Starr (949802) | more than 8 years ago | (#15475709)

Quite right - Submitter is not looking for a word processing tool, necessarily. Just something that allows you to fall back to an earlier revision if necessary, and maintain accountability for changes. Subversion is really rather robust in this respect. You can branch off toward infinite if you'd like.

In a nutshell: You set up the central repository, and then everyone who might work on a file maps a directory to this trunk. Whenever you make a change to a document, you check that in to the central Subversion repository. It makes a note of who did what, and will update everyone else's copy of the document when they perform an update. In the event that two people change the same doc at the same time, it allows an outside agent (admin or the like) to see who added (or deleted) what, and accept changes accordingly. It is very handy for maintaining a productive work environment, especially with regard to coding, for example. Everyone can maintain a full copy of the code that is (hopefully) compile-able for testing, even if they are only responsible for a small functional subset.

As a disclaimer, my use of Subversion is limited to an isolated network. It is entirely self-contained and inaccessible from outside, so we don't have to worry about security or any fancy remote-access modes. Also, it is only used for tracking changes in Python and C files and basic .doc files. I'm not sure how it handles more advanced file types.

Sharepoint has revisioning (2, Informative)

MexicanMenace (673792) | more than 8 years ago | (#15476055)

The poster says they're using Sharepoint. It already has the capability to "check out" a file instead of just opening and saving it. Click the down-arrow next to the document name and select "check out". The document list will then update to show that you've got the document checked out. When you've edited and saved the document, do the same and select "check in".

Doing this keeps previous versions of the document. If you just open, edit & save, then you're just updating the current version of the document.

Re:Question I ask my coworkers too (1)

mikewolf (671989) | more than 8 years ago | (#15476080)

I still think you are missing an important part of the question... It is asking for tools to manage functional requirements, not just to manage changing documents and concurrent edits.

I've had a very similar discussion in my company, and the main problem is change management (i.e. keeping an up to date, relevant, clear and concise repository of functional specs that is 1.) not impossible to manage and 2.) easy to view the definition of the current functionality).

(on a side note, at my company we thought that wiki's looked to be the most promising as developers, but finally decided that it was just too hard to manage the content and change process with the ones we evaluated.)

All-encompassing tools (3, Informative)

masklinn (823351) | more than 8 years ago | (#15475538)

While I haven't managed to get them integrated into the workflow yet (working on it), I find tools such as Trac [edgewall.com] extremely interresting and full of potential: Trac integrates a wiki (for base documentation) with a bugtracker (bugzilla-like) and a Subversion repository while linking all of them together (you can use the SVN commit comments to link a commit to a bug, track them from the wiki, generate timelines, ...)

And important document should never ever be stored in proprietary binary formats: you can't decrypt them yourself, can't change bugs, can't do anything.

Re:All-encompassing tools (1)

masklinn (823351) | more than 8 years ago | (#15475557)

Precision to my previous post: when I say that I haven't managed to get them integrated into the workflow, it's not in the technical sense of the term (installing Trac is fairly trivial) but in the hierarchy-related one, management isn't interrested in changing it's habbits or in seeing the dev teams change their habits.

Non-binary formats (1)

Rob the Bold (788862) | more than 8 years ago | (#15476149)

And important document should never ever be stored in proprietary binary formats: you can't decrypt them yourself, can't change bugs, can't do anything.

Amen to that. One of the nicest things about non-binary formats is the ability to difference versions without any special tools.

Trac (3, Informative)

XeusTsu (965623) | more than 8 years ago | (#15475558)

I myself like using trac which I believe is opensource and works off of a subversion tree. To my knowledge Subversion is meant to be a better solution then CVS for most items, and can be used on it's own.

On the other hand, my company uses Subversion and TortoiseSVN as a shell extension, edit files locally and simply commit them to the subversion repository. You can do all the blame, branching/tagging you need, but our company is likely much smaller then yours. Something to look at I guess.

Re:Trac (2, Interesting)

gregmac (629064) | more than 8 years ago | (#15476034)

Since trace is just a frontend to a subversion repository, and tortoisesvn is a frontend to subversion (client) itself, using all 3 is perfectly acceptable - i do it all the time (for my windows development, anyways).

But I do agree, Trac is a great tool. Combination of wiki + ticket tracker + roadmap + svn browser. It's great because it's all integrated: you can make wiki posts that say "this will be done in milestone:1.2", tickets that say "Fixed in [265]" (revision), or svn commit messages saying "Fixed ticket #23" and everything becomes a link (see: http://projects.edgewall.com/trac/wiki/WikiFormatt ing#TracLinks [edgewall.com] ). The wiki is great for documentation, researching new ideas, etc and ties in very nicely.

The wiki may or may not be an answer to the submitter's question (for the analysts), depending on how closely related the documents are to the code, and if they can get the analysts to switch from word to wiki syntax.. but it's definately worth checking out. So far everyone I've introduced trac to loves it.

Baby step #1: source control + existing docs (5, Interesting)

dsandler (224364) | more than 8 years ago | (#15475586)

It's pretty shocking to change everything (document format, writing environment, collaboration tools) all at once. Start with reasonable source control, the best bacon-saving device you can get. Have everyone check existing docs (Word, HTML, whatever) into source control; Even though diffs are meaningless for the binary formats, the other benefits (versioning, collaboration, remote storage, tags, platform independence) are huge. It's the quickest way to put an end to the madness of emailed .doc files and accidental deletions.

If you've got a lot of Windows users, go with Subversion [tigris.org] and get everyone to install the TortoiseSVN [tigris.org] shell extension, which offers the most natural GUI for new (and experienced!) users of version control.

Once everyone's comfortable with SVN, you can then start migrating to text-based document formats in which the source control diffs mean something (LaTeX, XML, reStructured, etc.)

Re:Baby step #1: source control + existing docs (1)

kieranbenton (642814) | more than 8 years ago | (#15476076)

Its probably worth noting that TortoiseSVN integrates with Word and Excel to do document diff's between revisions. Very handy!

Probably not helpful at all, but what I do... (1)

martinultima (832468) | more than 8 years ago | (#15475609)

I have about three or four machines that I tend to work on regularly, and most of the time what I do to keep up with files is just scp them back and forth between the machines (I run Linux, if you're wondering). As far as revision control, if I need something like that I usually just create separate directories and archive various different revisions in each. Depending on what I need to copy I may also have an NFS share set up for my own local network, usually read-only for reasons clear only to me. Granted, there are a few big differences – my needs are considerably different, and besides that I'm likely half insane – but it tends to work well enough for me.

If it helps, most of the files will either be various documents, especially schoolwork and/or novels I may be attempting to write, mostly never to be published – these tend to be copied between my laptop and desktop machines – or else various stuff for my Linux distribution, which move mostly between my two development boxes – a Duron-700 which does x86 stuff, and an AMD64 which handles the 64-bit version, CD burning, processor-intensive junk, and just about everything else.

Like I said, may not work for you, but it works for me, so may as well share it with the world, even if they don't give a damn :-)

Trac and Subversion (1, Redundant)

AccUser (191555) | more than 8 years ago | (#15475611)

Trac [edgewall.com] is a powerful ticketing system that integrates well with Subversion [tigris.org] , and is built around an easy to use Wiki. I would also recommend using TortoiseSVN [tigris.org] as a Windows client for both developers and non-developers.

Re:Trac and Subversion (1)

temporalillusion (688393) | more than 8 years ago | (#15475828)

My only complaint about trac is it's a pain to administer. At the time I was trying to have a seperate instance of trac for each project (different wikis, different bug databases, etc) and it was horrible. That was over a year ago however, so maybe it's better now? But otherwise I thought the tight integration between SVN, the bug tracker and the wiki all made for a great software project management resource.

Meta-answer (4, Informative)

Jerf (17166) | more than 8 years ago | (#15475645)

I doubt I'll have much to add to the long list of people describing their experiences with various systems, but I'll pop out this meta-thought: Your developers and "functional analysts" probably have wildly varying needs, especially if the "functional analysts" use word-processing documents like Word. There's no crime in given each group of people a separate system.

Your devs probably ought to get subversion because the continuing cost of using a sub-optimal source management system adds up to staggering amounts pretty fast. Your other writers probably aren't continuously branching and merging and doing all the other things subversion allows (if nothing else that's really confusing for most documents), so they can use a simpler, easier-to-use system that doesn't incur continuous costs due to confusion and documents getting mangled or destroyed due to incorrect use of the system.

The right tool for the right job.

(Note: I'm not saying you should use multiple systems; I'm just saying it's not a crime, if they solve different problems. If you can get your writers to use SVN, especially if they use something with a decent plaintext representation that stands a chance in Hell of merging, hey, great, more power to you.)

Re:Meta-answer (1)

ednopantz (467288) | more than 8 years ago | (#15475980)

Exactly.

What is the problem with keeping specs in Sharepoint and code in SVN?

Sharepoint is really good at tracking/merging Word docs. SNV is really good at tracking/merging text files. Why not use both?

Requirements Management (1, Interesting)

zotster99 (979823) | more than 8 years ago | (#15475668)

Alot has been happening the the Requirements Management space lately. Moving away from documents and into Requirement Management Repositories is alot simpler and promotes interaction. Applications such as Borland's CaliberRM or StarTeam allow users to enter their specifications and requirements as electronic forms. Once requirements, change requests, or specifications are entered into the system, users have the option to export to various formats such as MS Word / Excel. Greater tracability and auditing is available in this model because change requests, defect management can all trace back to a functional requirement. Using tools like Borland StarTeam SCM even allows you to go further and trace requirements to actual source code. Another big benefit is that seeing changes between revisions in Requirements is alot easier since there is no diff'ing involved.

Re:Requirements Management (1)

penfern (760298) | more than 8 years ago | (#15475879)

Have a look at Alfresco. It's an up and coming general Content/Document Management system, dual licensed, very flexible.

Ease of Inertia (1)

fm6 (162816) | more than 8 years ago | (#15475691)

Your big problem is your analysts. They want "ease of use" which is just another way of saying "we like working with a word processor". But the messy data maintained by a word processor is incompatible with your other goals. You need a well-structured format such as XML/Docbook. (I mention that specific format by way of example, though it's a good general-purpose solution if you want to maximize your reliance on off-the-shelf technology.) Imposing structure on your document base is moderately difficult, but well within the ability of any semi-competent software wonk. Persuading people that they have to give up their word processors is much, much harder. As the flame I'm anticipating in response to this post will certainly reveal.

Talk to End Users (LaTeX+subversion vs. Mediawiki) (1)

Noksagt (69097) | more than 8 years ago | (#15475729)

I use subversion + LaTeX when I can. I use vim with latexsuite & usually use subversion in another term (although I have the subversion plugin for vim). Each individual product has already been suggested above, and they are powerful in combination.

That being said, it is not usable if you're dealing with end users who don't understand the tools. Your FAs sound like such users. The front ends for LaTeX have scared end users and/or write pretty bad LaTeX (which causes those who hack it in vim to scream). Few are well integrated with version control tools. TortoiseSVN is fairly friendly, but most people aren't used to working with version control systems & it might be better to use something integrated.

In short, you need to figure out your documentation needs (What will the final product of this documentation process be? What markup is needed? What do you hope past revisions of documents will gain for you?) with end user ability (Can your users be trained cheaply to use specialized tools?).

In contrast to my personal use of subversion + LaTeX, I have found I have to have distributed collaboration with others on "throw away" documents and web pages. MediaWiki has come to the rescue. There is a plugin to allow knowledgable users to input TeX. There is a patch which allows page restriction or you can jail a whole installation to specific users. There are many other wikis and other apps that may also work for you. In particular, for specs, you might look at bugzilla or other issue trackers. Just figure out what you need, choose a few likely candidates, and hold hallway testing.

Trac/Subversion + Knowledge Tree (2, Informative)

Qbertino (265505) | more than 8 years ago | (#15475755)

Many have mentioned Trac/Subversion allready and I second that.
For managing Documents I would use Knowledge Tree [ktdms.com] . The open source version is cool and the professional edition adds in all the stuff managers like.

Re:Trac/Subversion + Knowledge Tree (1)

bsaxon (823024) | more than 8 years ago | (#15475905)

I agree with Qbertino. Trac (http://www.edgewall.com/trac/) will allow you to integrate Wiki/Versioning/Tickets/Roadmap/Timeline. This will work best in amongst the software developers, but may not be something the functional analysts will find familiar or easy. Although, I would imagine heavy adoption of this across the whole company would be the best situation for increasing productivity amongst the software developers. If you're looking for something to handle the duties of Sharepoint and Microsoft Word, get Knowledge Tree and consider the professional version w/ Windows and Microsoft Office integration. This won't offer any direct benefits for developing software but will handle document management quite well, including versioning, checkout, etc. Think about how you could use both. This will probably be your best solution.

Re:Trac/Subversion + Knowledge Tree (1)

argle2bargle (794789) | more than 8 years ago | (#15476322)

I have also implemented open source Knowledge Tree for my companies documentation.
I really like version 3, its a huge improvement from 2.
It's got a nice group and role based permisions system, its free, and best of all....

The users don't seem to have many problems or questions about it.

Microsoft Word and Sharepoint (3, Informative)

Karma Farmer (595141) | more than 8 years ago | (#15475800)

Based on the requirements, you should be using Microsoft Word and Microsoft Sharepoint.

If those don't fill your needs, then either you've failed to describe your requirements or you've failed to correctly set up the software.

Re:Microsoft Word and Sharepoint (0)

Anonymous Coward | more than 8 years ago | (#15476199)

I concur. There isn't anything in the original poster's atated requirements which can't be done rather easily with MS Office/Sharepoint.

If the analysts are already comfortable with that particular toolset, why does it make sense to migrate to something completely foreign to them? Better in this case that the technical staff should learn how to implement the features of what they already have.

Depends very much on your analysts (4, Interesting)

Circuit Breaker (114482) | more than 8 years ago | (#15475853)

Where I work, developers use CVS exclusively. It has its quirks, and we've considered alternatives, but the combination of CVS+TortoiseCVS+Jalindi Igloo (Visual Studio integration)+Jira is unbelievebly hard to beat (Subversion doesn't have a reasonable SCC connector, and nothing else has anything that comes close to TortoiseCVS -- even TortoiseSVN is clunky and awkward by comparison. Oh, and CVS mergepoints work perfectly, unlike the nonexistent merge tracking capabilities of Subversion).

When our "functional analysts alike" guys wanted version control, we naturally gave them the tried-and-tested CVS, and gave them instruction on its use. It was a horrible failure. The update-edit-change-commit cycle which is so trivial to developers just didn't work. The people are not dumb - just have a different mindset. We had also tried a Wiki (MoinMoin, works well for devs), but its inability to search or version Excel files make it irrelevant.

Eventually, much to my dismay, we settled on Sharepoint. And while it's clunky, horrible, keeps only the 7 latest versions of any file, has no branching and is often inconsistent with error messages, them users are able to work with it without requiring assistance.

Do not confuse a feature list with applicability of a tool to the situation at hand which, it appears, might depend more on the people involved than anything else.

another option - plone (1)

akookieone (530708) | more than 8 years ago | (#15475908)

Who hasn't had to deal with this?
I ended up using plone [plone.org] with the zWiki product and a versioning product (CMFEditions is your best bet). Plone/Zope provides a very powerul platform to start with, adding a few products on top of this and you have what you need, and then some.
There are tons of add-on products, like defect trackers, calendars, source control integration, also a few project management products you can plug-in as well, though I never bothered with such things.
It also supports FTP and WebDAV access for mass file upload, and there are products to make it easier to use various types of docs, be they word or open office.
Anyway, I've used it for a few years now and I couldn't be happier with it - we just keep using it for more purposes.

SVN + WebDAV + Autoversioning (5, Informative)

HFShadow (530449) | more than 8 years ago | (#15475989)

http://svnbook.red-bean.com/nightly/en/svn.webdav. autoversioning.html [red-bean.com]

From the SVN Handbook:
"Because so many operating systems already have integrated WebDAV clients, the use case for this feature borders on fantastical: imagine an office of ordinary users running Microsoft Windows or Mac OS. Each user "mounts" the Subversion repository, which appears to be an ordinary network folder. They use the shared folder as they always do: open files, edit them, save them. Meanwhile, the server is automatically versioning everything. Any administrator (or knowledgeable user) can still use a Subversion client to search history and retrieve older versions of data."

Mod Parent Up. Was Re:SVN + WebDAV + Autoversio... (1)

danpat (119101) | more than 8 years ago | (#15476205)

That's exactly the setup I've put in place in a couple of places. Works brilliantly. Non-technical and recalcitrant users simply get another folder that they can drag-and-drop files to. MS-Word and many other tools understand WebDAV and will issue LOCK commands, so other users know when files are being worked on and won't conflict. There are the occasional "drop new copy over the top of updated one" type-errors, but that's the trade-off for ease-of-use. Pick what's more important to you.

Go Wiki, go Confluence (1)

jordandeamattson (261036) | more than 8 years ago | (#15476115)

I would strongly recommend going with a Wiki with access control. This will allow your team to collaborate on various documents. I highly recommend Confluence http://www.atlassian.com/software/confluence/ [atlassian.com] from Atlassian Software.

Everything your analysts like about the combo of Word and Sharepoint will be provided in an easy to use package, plus everything that the "geeks" want, need, and love will also be provided.

Yours,

Jordan

Good luck (0, Offtopic)

Orion Blastar (457579) | more than 8 years ago | (#15476126)

I tried to implement a Wiki at my last employer to keep track of changes in the software and database as they happened very quick and were hard to keep track of with a normal Word document. I would get emails from a coworker instead of a Word document and I kept all of my changes in a Word document so it would be easier to read and look up. I set up a web server on my laptop with a Wiki site after the owner advised me to find a better way to keep track of documentation. The network administrator saw that I had a web server and had me shut it down. It was only on a local Intranet and it gave me a better idea of how changes were being implemented. I had tried to use many tools like that to help bring order out of the chaos they had, but I guess they just wanted to make my job a lot harder so it would stress me out and force me to quit? I had a lot of ideas for the software and database that coworkers called me names over having those ideas. I see now that the web site for the company has all of my ideas as product features now, after they fired me for no reason given. I was only highed to migrate their database to SQL Server and fix the flaws and bugs and performance problems in their software and database, once I fixed all of that, I was unjustly fired. I guess they got what they wanted out of me, to take them to the next level and then they threw me away like a used tissue.

Confluence fits your requirements (2, Informative)

puppetluva (46903) | more than 8 years ago | (#15476163)

We chose Confluence at my firm ( http://www.atlassian.com/ [atlassian.com] ). They are the same people who write Jira (the project management system on a bunch of open-source sites). It handled all of our requirements (very similar to yours) and it works really, really well. I don't work for the company, but I feel good talking-up people who make good products. My favorite features:
  • WYSIWYG editor built in with an option to do wiki-markup if you want.
  • Full versioning of the docs and attachments
  • Full searchable indexing of both docs and attachments (even word, powerpoint, excel, and pdfs)
  • Customizable navigation and templating
  • Easily customizable permissions
  • It works great with open-source databases (postgres in our case) and pay ones and its searching is very powerful
  • You can be set-up and running in about 30 minutes
My favorite feature is that we don't have to mess with it at all. We set it up and both non-developers and developers get along with it well. I would chose it over Sharepoint or Notes in a heartbeat (both of which I used before and thought were a mess).

Alfresco (0)

Anonymous Coward | more than 8 years ago | (#15476181)

Open source with enterprise features, high quality and ease of use. Community and professional support available.
http://www.alfresco.com/ [alfresco.com]

Lucidoc (2, Informative)

Xofer D (29055) | more than 8 years ago | (#15476258)

It sounds like you want something like Lucidoc [lucidoc.com] . It integrates with Word and even IE, and does what you seem to want, I believe. It's pretty seamless, and used in health care document systems. Have a look at it and see if it does what you want; it sure would be easier than convincing MS Word users to use cvs or svn. Disclaimer: I am neither a vendor nor a user of this stuff, but I know one of the developers.

DOORS! (1)

m.elliot (979861) | more than 8 years ago | (#15476261)

I'm surprised nobody's mentioned DOORS (It's by TeleLogic [telelogic.com] ). It's a requirements matrix system that's extensible, powerful, and reasonably cheap if you're a mid-size (or larger) business. ..on a side note there's a modified Wiki by a Edgewall called Trac [edgewall.com] . I've not used it personally but it looks like the right stuff...

Telelogic's Doors (2, Informative)

bheilig (516136) | more than 8 years ago | (#15476266)

We use Telelogic's Doors [telelogic.com] It's good for large projects with multiple systems. It supports requirements tracability and revision history to the object (typically a paragraph). After you're done you can export it to MS Word and you can customize this process using a scripting language and Word templates. I work for a government contractor and the systems we develop include hardware and software efforts on multiple independent processors. It might be overkill for what you need.

Brian

Ok, get over yourselves (1)

jrgeek (541012) | more than 8 years ago | (#15476340)

All right, just because it's easy to put microsoft down and call them the evil empire doesn't mean that we should always do so. The simple truth is that sharepoint IS a good tool. It has version control and it's easy to manage permissions. I am by no stretch of the imagination a microsoft fan, but every once in awhile they DO make a product that works well and actually uses AD in useful manner. I know it's tough to get past a fundamentalist point of view (which is something you see on slashdot quite often) on not using microsoft. This is just counter productive in my humble opinion. I liken this matter to islamic and christian fundamentalists, they are just to stubborn to see the others point of view. Might as well be religion of computing...and it's really sad to see this coming from supposedly intelligent individuals in the technology industry.

Go for Alienbrain (2, Informative)

codesurgeon (979732) | more than 8 years ago | (#15476355)

Having individuals on the team without a development background and/or the need for a decent UI and all the features you could ask for in a version control system, I'd urge you to get your hands on Alienbrain. It is stable, easily accessible for non-techies, industry-proven and still the market-leader in game dev. You could of course look into UIs for subversion etc. but I guess something along the lines of Alienbrain would be most feasible in your case. And for the rest set up a wiki.
Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>