Stories
Slash Boxes
Comments

News for nerds, stuff that matters

Slashdot Log In

Log In

Create Account  |  Retrieve Password

Version Control for Documentation?

Posted by Cliff on Fri May 11, 2001 03:04 PM
from the CVS-for-.DOC-.XLS-and-it's-ilk dept.
CodeNation asks: "I'm a coder in smallish (~50 staff) company with a ~20 strong development team. We, the development team, have been using CVS, and CVSWeb to manage our source base for a couple of years. In the meantime, our corporate documentation has become a complete mess. By 'corporate documentation' I mean content such as Word documents, Powerpoint presenations, and Excel spreadsheets. Anyway, I was recently asked by the one of the bosses to put a document version control system in place for this corporate documentation. All this, and the system has to be usable by the non-technical." Ask Slashdot has touched on a similar topic but it's been about 2 years since that article. Has there been any headway in this area?

"Now, this would be a trivial task if:

  • The documents were text-based (i.e. the file formats weren't binary)
  • The entire company understood how to use CVS

However, neither of the above are true.

I took a look at CVSWebEdit, but unfortunately it's not quite there yet in terms of stability and usability.

Does anyone have any suggestions for a possible solution? What are you currently using for document control (remember these are Microsoft Office documents). Also note that although the developement team works on Linux boxen, the non-technical staff works in a Windows environment.

Thanks for your help."

+ -
story
This discussion has been archived. No new comments can be posted.
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More
Loading... please wait.
  • by Anonymous Coward
    I have implemented three different version control systems using three different products: Documentum, LiveLink, and DocuShare. DocuShare was by far the easiest to set up and maintain. It also required very little training for the end user and supports searching through document content. It's really a pretty slick system and it's written in Python.
  • Microsoft Visual Source Safe.

    Unlike everyone else who replied to you, I'm going to say more than "SourceSafe sucks ass!"

    I work at a windows shop, we use SourceSafe to store all our code (VB, C++, HTML & ASP stuff), and also documentation. For code, it's fine. (I mean, it's slow and ugly and shit, but it works fine. People who have worked there for many years say its never "eaten" anyone's file).

    But we do also store Word & Excel files in there (and Access mdbs), and for that, well, it's pretty pointless. Because I'm assuming that the asker wants to be able to do more than just have the latest version available - if that was all he wanted, the files would be sitting on a fileserver and he wouldn't be asking Slashdot. If you want to be able to do diffs, see WHAT was changed in a checkin, there's no simple way to do it with binary files like Word and Excel produce. Go on, diff them with SourceSafe - "binary files differ" is all it will tell you.

    There may be a solution (hell, doesn't Word store changes itself? haven't people gotten into trouble by publically releasing documents with old text "hidden" in them?) but SourceSafe isn't it.

  • Why not use a simple backup system that maintains a searchable database of backed-up file versions? There are some nice ones out there that do this, even one that uses an Explorer plug in to give you a view of backed up data and the ability to restore it.
  • I work in what is pretty much an ``all Windows shop'', yet somehow we managed to switch to using CVS instead of VSS (not quite entirely). A lot of the documentation is in Word.


    However, I write all my documentation in LaTeX, using encapsulated PostScript for diagrams. This isn't a problem, because I can generate a PDF which is stored in CVS along with the text source files. I do this for software internal documentation as well as for presentation materials (slides).


    Binary files are okay in CVS as long as they are derived objects rather than primary objects. What happens during a merge is that you merge the primary objects (LaTeX source files), and regenerate the derived binary object (PDF) from the primary sources and commit the results. However, when the primary objects are non-mergeable (e.g Word documents) you are in trouble. If two people modify the same Word document on separate branches, there is no way to merge other than by hand editing.


    With LaTeX, the documentation can be broken into many files which are stitched together with \input directives. This was an advantage because at one point I was working in a small team on the same document. Using multiple files minimizes the amount of back and forth merging that takes place with concurrent development.


    I have a few LaTeX macros which can be used to embed CVS keywords like $Id$ in a special way into the documents. The macro actually collects these into a file during latex processing. A special appendix is then added to the output which lists all of the source files and their versions. This is called the ``Bill of Materials'' and tells the reader exactly what versions of the files in CVS correspond to the hard copy.


    Here is a good advocacy page you can throw at people who think that word processors are actually suitable tools for intelligent documenting: Word Processors: Inefficient and Stupid [wfu.edu].

  • Are you sure these guys are programmers? I put most of a whole company on WinCVS within the last half a year or so. Looking at the /home directory of my CVS server, I see about 70 accounts belonging to users who access CVS over RSH from Windows boxes. I, along with a few others, provide minimal support besides setting up new accounts.
  • I've used VSS for some time, including storing of documents. For non-enterprise class stuff, it will do the job. It's not a client-server app (the VSS client directly accesses the database files via their UNC path). It can be a pain due to corruption when used over unreliable or slow links, e.g. VPNs. For a lot of things it's a cheap and usable solution.
  • by jelwell (2152) on Friday May 11 2001, @01:16PM (#229167)
    Xanadu [xanadu.com.au] was made for this.
    Joseph Elwell.
  • That's what we do where I work. We don't have non-technical people, but having those is not an excuse.

    LaTeX is easy - there's windows environments for it. Even without it, a trained chimpanse should be able to write \chapter{Title} to start new chapters. For non-mathematical writing, that's about all there is to LaTeX. Maybe \textbf{bold} too, but then it's about covered. Argumenting it is too hard is going to take better arguments than "remembering a small handfull of words (so-called codes, even though they're often real words) is too hard".

    And CVS ? Well, Cygwin (from sources.redhat.com) has CVS and it works beautifully. Don't tell me that writing "cvs update" is harder than locaing the correct share on a server. Just configure CVS for the non-technical people so they don't have to worry about CVSROOT.

    Resolving CVS conflicts ? Anyone who's had their word document changes reversed because someone else corrected a spelling error in their document while they were working on it is going to be really encouraged to learn about conflicts. Usually though, conflicts are easy to resolve in non-code (documents).

    If you have to argue against this, please make up a sane argument - saying "but people only know word" is not an argument. With this solution they don't even *have* to know word.
  • Since XML is a text-based meta-format, any XML document will work fairly well with CVS. Unfortunately, there aren't too many easy-to-use office apps that generate XML. (The next version of Excel is rumored to, but it doesn't look like Word will.) So you're probably better off using something like Visual Source Safe or Documentum.

  • Actual MSs product is crap. There is an add-on, though, called SourceOffsite, which is much, much better see http://www.sourcegear.com/
  • Corporate documents have much different needs than programs. Documents need to be searchable, categorized, approved, etc. You need something that will tag a document with

    * Current Version
    * Related Categories
    * Awaiting Approvals
    * Approvals Received
    * Place in the system
    * What time to re-review
    * Notes for a document

    This way, anyone can easily find a document, and find any past versions. New documents will have to go through a formal approval process, and people will be automatically notified when documents need to be re-reviewed. Notes can be attached for clarification and questions.

    CVS can do versioning, but not the rest. And, CVS's versioning is MUCH too complex for what you need. You don't need branches/tags/everything else with corporate documents. You are never going to merge between branches. You just have the document and its version.
  • You're looking for a system like what you're used to, CVS. That's an automated solution suitable to maintaining computer-code (plain text.) Here parts are checked in & out by coders, reviewed other coders & managers, builds produced, used by QA, etc.

    Documentation folks are used to a different work-flow model. Traditionially there are copy writers, graphic artists, layout folks, and layers of editors. Their workflow is folders, or in the computer-age their representation, directories.

    They're analogous models but there are differences. In writing & graphics the latest version is not always the best. Content, as you've learned, can come from many sources and in different formats. Materials are used & reused in bewildering permutations. While automaton systems exist (and are at least as sophisticated as CVSs) they require much more customization.

    Frankly you're the wrong person for the job.

    While you may have been great at organizing materials and workflow in your field you're now outside of it. It's a different culture (albiet possibly dysfunctionial in this case) and for you it's terra incognita. The tools are different, the processes are different, the constraints are different, the end products are different.

    The best strategy would be to bring in someone knowledgable in documentation to evaluate the current staff & systems and make some suggestions, possibly implement them. If things have gotten to be "a complete mess" then there's undoubtably a number of problems and deus ex machina won't fix them.

    The problem could well be poor organization. It could as well be unqualified staff, understaffing, poor management, lack of support from other parts of the company, bad technology choices, etc.

    You're not really qualified to judge any of these, good as you may be in your area and in spite of the general problem-solving and management skills you might have. It's as if one of these folks were asked to come in and help shape things up when the R&D folks are late writing a release.

    Indeed if it were me (and I've been invited to undertake similar projects in my career) I'd decline this "opportunity". What you're being asked to do has nothing to do with your competencies. Indeed if the only point is congruence is familiarity with CVS then the bosses would be better suited - they do more general writing and live more in the world of memos & Powerpoint slides.

    You were hired to code. Presumably you're good at that. You weren't hired to analyze business processes, research & specify documentation automation systems nor to implement them. Finally, if you do this you'll be the guy for this in the future, any issues regarding it will end up on your desk from now on. Is that where you want your job to go?

  • I noticed your company size was quite small. If you are already using CVS then you have someone's attention regarding open source projects.

    I would suggest you take a look at BSCW [bscw.gmd.de].

    Features: web interface, users/groups, upload, drag and drop, email notifications, revisions, workspaces, delegation, etc....

    I put up BSCW at a past job with a team about the same size as yours. It was okay but making sure people could get to it was the main issue. i.e. this was back when getting folks to use a web browser was a chore ;)

    You can tweek it a great deal and there are drag and drop "goodies" utilities for the form upload challenged.

    -Jay

  • As much as I dislike MS, they have a product that would probably work for you. Specifically Visual Source Safe.

    Since you've stated that the droids and the techophiles don't use the same OSes, it almost makes sense for the droids to be using a MS centric VC application. It probably handles Office files natively and has a pretty interface.

    On the downside, you'll pay mucho diniro for it and you'll need an NT server for it to run on (speculation on my part).

    On the other hand, CVS handles binary items just fine, you just can't include RCS tags in them. If you have a nice web based wrapper, then CVS would work fine, cause you can show log items independently through the interface. Browser upload and DL would solve the checkin/out problems.

    May the force be with you.
  • As noted above, CVS can handle binary files just fine as long as you tell it it's getting a binary file. Most CVS GUI clients can also handle them.

    What you're missing here is the ability to browse versions via cvsweb and the like, and do visual diffs on them, which are beyond the scope of CVS seeing as they'd involve DOC- or XLS- to-HTML conversion, among other things.

    This is usually why a company or organization invests in a commercial DMS like Documentum, or in a commercial source-control system, depending on how your needs skew. Doing that stuff and making it work well and quickly while still easy to use is not simple, and doing a good job of all the format conversion and parsing requires the commercial conversion filters that Inso and Adobe have owned over the years, and which are in nearly every product that does good conversions of MS Office documents.

    That said, you may be able to assemble something out of the following, for example:
    1. CVS, and whatever client interface you want to use to get files in and out
    2. The GPL'ed mswordiew Word-to-HTML filter or its cousins
    3. The filters used by Gnumeric for Excel import and HTML export, or cousins thereof
    4. A set of directories containing HTML conversions of all versions of all documents
    5. A web search engine
    6. cvsweb, rewired to perform diffs and display contents based on the HTML "ghosts" rather than the original files
  • It's fairly easy to use, everyone can read it, and it's not editable, which in many cases is a plus.

    Plus, all the change tracking in Word goes away (I won't call it version control, because it's not).

    Actually, there are some nasty bugs associated with change tracking (screws up automated numbering of figures), so it's another feature of Word I never use.

    Jon Acheson
  • I've been in your shoes, and my opinion is that it's better to keep it simple, but organized.

    I don't like using CVS with nontechnical people who haven't been trrained for it. They are as likely to accidentally overwrite the new version of the doc with the old as they are to save themselves any trouble. So, if you go with CVS, definitely factor in training for everyone.

    But, if that won't fly, maybe you should just consider using a plain old network directory, with some careful setup.

    Basically, use grouping and network access privileges to give each workgroup their own directory noone else can edit. Each software project has their own subdirectory, and each set of docs for a version of the software a deeper subdirectory. Keep the different versions of the docs totally separate (don't try to be clever and have a shared graphics directory), and archive the old docs in zip files so that nothing gets lost or written over.

    That's a start. There is a whole lot more involved in doing this job right: you have to build standardized templates, get the users to enter information for each doc (this can be done easily using a macro that makes them fill out a form when the doc is created), collect that information and set up search tools and indexes.

    It's a complicated subject, and that's the short version. If you want to read more, check out my my 16-page Guide to Standardizing and Organizing Documentation [fast.net]. It's not quite where I want it to be yet (second draft but not finished), but I think it might be helpful.

    Jon Acheson
  • Too bad Visual Safe Source has eaten a few of my projects in the past. I wouldn't recommend using it if it can at all be avoided. And if it can't, make frequent backups.
  • Actual MSs product is crap. There is an add-on, though, called SourceOffsite, which is much, much better see http://www.sourcegear.com/

    While generally I just ignore such claims on Slashdot, this just takes the cake and pushes me to respond. SourceOffsite (I use it every day so I'm pretty aware) is basically SourceSafe Lite : All the same features used in the same way, just less of them. How in the world is that so much better?

    The good thing about SourceOffsite is that it does have a server component for low bandwidth connections, but without that requirement it'd be enormously stupid to use it in an office.

  • Friend of mine and I thought this one up to get around this problem. What you do is have them save to a specific volume on the network. However, Every time you do things to the directories, it triggers scripts. This is almost a no-brainer on macos with folder actions in applescript, and I suppose you could to the same with VBS as well.

    So when they Mount the networked volume, what really happens is a script does a cvs checkout for them, then they see the mounted drive locally. Then they save, folder action converts .doc to RTF, .XLS to tab seperated...this way the eloi can use .doc...but you're still using text formats you can use with cvs.

    You can do a commit after that, or when they unmount the volume...a script does a checkin/commit. Season to taste.

    So that's it....basically, you use scripts to abstract the user from CVS. The happy beneifit is by using text formats...you clean all the macro virii out of your data.

  • The most obvious solution is to teach them how to use cvs. The other option is to use Microsofts own source control software SourceSafe. It handles binaries cause it can handle VB forms. It is easy to learn as it is Microsoft and works just like any other M$ product.

    The third option is to try PVCS which is another form of CVS / SourceSafe, but made by a diffeerent company. It has a GUI just like SourceSafe and handles binaries.

    We just use a fileserver and people edit from there. You can set up word docs to keep track of who did what edits and change colors. There is an option in it as well.

    I don't want a lot, I just want it all!
    Flame away, I have a hose!

  • by Osty (16825) on Friday May 11 2001, @11:19AM (#229209) Homepage

    There are several possible solutions to this problem, as I see it. If you want to go the commercial route, Visual Source Safe is the normal standby, or any other commercial source code repository systems would work. VSS has poor merging capabilities, but when you're dealing with Word files or PowerPoint slides, that's not so much a problem (as Office can "version" the files for you -- though make sure to strip the file before releasing it to customers). Also, the upcoming Office XP has Sharepoint capabilities, and is very easy to use (easy enough for your pointy-haired boss to figure out, even).

    On the other hand, you could setup CVS anyway, even though you said you'd rather not. There are a few nice win32 GUIs for CVS, so the end-user experience shouldn't be too bad. On top of that, if you use CVS for your documentation, you can keep that in your source tree. One less tree to manage, and you'll always know where the documentation is. And CVS can handle binary files just fine. Just don't expect to be able to merge changes.

    Of course, another (less likely) option would be to move all your documents to HTML, or XML with a set of defined XSLs to transform them. That way, you could do merging just fine. However, that's most likely not a workable solution if you deal with anything but Word documents (since word can save to HTML instead of .doc).

  • What you're looking to do is called "Knowledge Management"

    [Plug]

    I briefly worked for a company in New Zealand called SilentOne [silentone.com] on their eponymous KM product. Not only were those kiwis awesome to work with, their product was very cool. While it ran on Windows only, it was a very good solution when compared with some of the others out there (such as FileNet and Lotus/Domino).

    Obviously, by using Linux, this product isn't useful to you, but I found it very intuitive, and it's integration into the Office toolbar very helpful (just like the CVS commands built into XEmacs). It had a web-interface which could embed Office apps into it, as well as the interface within office.

    I'd reccomend it to anyone here stuck with a Windows-only shop (and boy, there are way too many of those...)

    [end plug]

  • There are a number of good tools out there for version control - however there are very few that can handle binary files in a "good" manner.

    Some issues:

    One - Binary file formats - such as MS Word - cannot have diffs run on them that are meaningful - a binary diff will result in a file larger than the two original files. So most version control programs will store binary files as seperate versions - but will NOT show the differences between the versions.

    Two - Microsoft HAS some built in support for versions within Word - however this will quickly result in VERY large files - which get increasingly less useable. Also note, that this will be ONE file containing all versions - if you "version" this file, you will have TWO files with different sets of the underlying versions.. sounds confusing? It would be.

    Three - There ARE version control programs that have worked with Microsoft to learn how to understand the underlying MS file formats (I believe Clearcase may, possibly MS's own Sourcesafe (which is otherwise a dangerous version control software to use since it can have data integrity problems) and possibly a few others.

    So - what would I recommend or suggest?

    First - Look carefully at WHAT you are intending to version. Is it a collection of documents (i.e. a full manual)? Individual documents that change over time? A whole project structure (say a website for online help?) Or something else?

    Can you seperate out the FORMATING (which might be in MS Word) from the content? For example by using a Master document format - importing TEXT documents into MS Word? This would allow great flexibility in versioning the underlying text documents, keep a smaller MS Word file, and that file could be "versioned" storing copies of each successive version?

    Second - For simple document management systems, (which run on Linux but can be accessed by any browser) look at a system like InfoPlace - simple, open source (I think) and easy to use. It is however not a rigorous version control system, but a partial version control system.

    Hope this is helpful - I spent 2+ years teaching and managing version control for a very large development operation (1000+ developers worldwide).

    Shannon
  • There are GUIs for CVS for many operating systems (including Windows and MacOS) at cvsgui.org [cvsgui.org].
    Non-technical people can be teached how to use 'add', 'update' and 'commit' in 15 minutes, at least it has worked in my company. (They use WinCVS for exchanging Excel documents with external clients and are happy with it.)

  • Too bad Visual Safe Source has eaten a few of my projects in the past.

    Just as another voice (and remember that these stories aren't statistics), I also know of a VB shop (a very talented one that took good jobs within the scope of VB and delivered good apps, so I assume they knew what they were doing) that had their VSS bit the big one. When they restored from backup, it did it again. And again. Something had broken deep inside and caused a logic bomb that always eventally exploded. They eventually checked *everything* out of an old version, killed the system and rebuilt, but it cost the entire company (all sales documents, templates for various company functions, etc. were in there) a couple of weeks, and got them some upset clients.

    But, otoh, they are still using it...

    --
    Evan

  • Yeah, you're definitely in the groupware world now, man. Source code control systems are just not designed to support complex, rich document sharing by non-technical users. Suites like Lotus Notes/Domino and Exchange, however, are designed for very little else.

    Check out Domino.doc [lotus.com], which is a super-enterprise-grade document collaboration platform that does versioning, archiving, searching, approval and workflow, etc. Not sure if it runs on Linux, but the core of Domino certainly does.

    And, yes, I know that nobody wants to admit it, but this is really the area where the MS Exchange + Office platform excels (ooh, accidental pun). Where Lotus needs an add-on (.DOC), much of this searching/versioning is built into the core MS software. Of course, then you have to start administering an NT server... --JRZ

  • There are plenty of web interfaces for CVS. We switched from PVCS to CVS where I work a year and a half ago, and people still thank me for getting rid of PVCS. The big problem with documentation is binary files don't version control very well with any software. A good solution would be an easy to use word processor that save's in xml and can be converted to HTML, Word, etc... I don't know anything like that that's easy to use. Lyx [lyx.org] is the closest thing I've found, but it's a long way away. I once started to look into Adobe Framemaker for this purpose, but didn't bother because it's way too expensive.
  • by Ralph Wiggam (22354) on Friday May 11 2001, @11:51AM (#229220) Homepage
    You guys should use the document management system that my last company used- total chaos. Every user creates a directory called "Bob's stuff" or "BSR" or something similar. Then all of the files they work on, no matter who else will need them, should go in the "Bob's Stuff" directory. Each file should be given completely incomprehesible names like "ClientData.xls", "JimQuote.doc", or "CSIQ12001rpg.ppt". That way when you need something, all you need to do is find the person who worked on it first and have them remember what they called the file. The set up and maintnence costs of this system are nearly nill. All you need for it to work are employees with photographic memories who never quit or die.

    -B
  • If you'd love to check it out, but the links on cvshome.org point to wincvs.org for TortoiseCVS, and that domain, according to NSI whois: Record expires on 08-Mar-2001. So try this link [sourceforge.net] instead, it works!
  • Greenstone [nzdl.org]

    "Greenstone is a complete digital library creation, management, and distribution package for Unix or Windows. Users create collections by gathering a set of input documents, specifying a configuration file, and running the build script. It provides full-text and fielded searching, browsable indexes, customised formatting, metadata extraction (acronyms, languages, etc), a Z39.50 client, and many other features. It supports many input formats, the interface is configurable and multi-lingual, and collections can be distributed on the web or on CD-ROM."
  • Sorry for the shameless plug (I work for Open Text Corporation [opentext.com]), but Livelink [opentext.com] is a great document management system product. It may be out of your price range, but it does allow you to have versioning on your documents, and it has a whole whack of other features that many enterprises demand.

    It seems that they're marketing it now as "a highly scalable and comprehensive collaborative environment for the development of Web-based intranets, extranets and e-business applications." Oh dear.
  • by mughi (32874) on Friday May 11 2001, @11:25AM (#229233)
    I'd recommend looking into StarTeam [starbase.com] from StarBase [starbase.com]. And this is even despite having been a developer there a while back :-)

    As a developer, I usually prefer CVS, but StarTeam works quite well for a whole office, Word docs and all. For the Windows-based world you mention, it seems quite appropriate. They have many different clients, and I've seen it used in mixed Windows & Solaris & Linux environments.

    In general, if a shop can't use CVS, and especially if they're using SourceSafe, I can in good conscience recommend it. And remember, friends don't let friends use SourceSafe :-)

    IANAL, YMMV, etc. I'm not sure if it will work for you, but it's definitely worth investigating

  • I searched, but no-one else seems to have suggested this. Use a wiki. I recommend MoinMoin [sourceforge.net].

    It is usable by non-technical users (a *lot* simpler than MS Word, certainly), and keeps a complete revision history, and can show diffs. Can be installed on NT with IIS5 with full functionality.

    The down side is converting existing documentation to use it, although most solutions to your problem will involve that to some degree.

    -Spiv.

  • True... and the problem with the files being binary can be solved by UUencoding them, first.

  • by Hard_Code (49548) on Friday May 11 2001, @11:43AM (#229249)
    CVS done right. [tigris.org]
  • by TheCrayfish (73892) on Friday May 11 2001, @11:17AM (#229263) Homepage


    Check out the products available from Hummingbird [hummingbird.com], Documentum [documentum.com], and Eastman [eastmansoftware.com]. A long list of document management vendors lives here [google.com].
    ---
  • by Speare (84249) on Friday May 11 2001, @11:26AM (#229273) Homepage

    Maybe I'm cynical but your stated goals of

    implementing version control and

    making it usable by nontechnical people

    You face one major uphill battle.

    Many nontechnical people have a hard time understanding a hierarchy, or of file types; this is expressly why Windows 95 defaulted to hiding file extensions and the subdirectory trees.

    Add to that the complexity of "where in the hierarchy does this file permanently belong," and the question "at what point in time was the file in a condition you liked?," you get into a major learning curve. Describing a sandbox is a task unto itself. Undisciplined developers often grok CVS but still don't use the delta comments in any meaningful way.

    That said, VMS is probably your ideal here for simplifying version management. Too bad it was an integration into the filesystem itself, and didn't expressly deal with multiple writers or delta comments.

    For those who haven't used VMS, the filename included a version number: name.extension;version . If you neglected to mention the version number in a system call, it assumed the newest. Every file opened for writing got the next version number and left the old versions untouched; every file opened for read-write cloned the newest old version first and bumped its version number. This builds into a large list of ;1 ;2 ;3 ;4 ;5 ... ;632 version for each file. You could easily back them all up, or prune to the newest version.

  • by iguy (89163) on Friday May 11 2001, @11:46AM (#229279) Homepage
    Microsoft doesn't even use Visual SourceSafe internally. It can't handle large projects. They actually use Rational ClearCase for the majority of their Source Control.

    Doesn't say alot for the product.

    The other thing is SourceSafe has problems with more than 200 projects in its repository. It starts Corrupting the data. Not what you want to see from a source Control system.

    ----
    Just remove the spaces and do the intelligent thing to email me.
  • Great idea, except that good developers know not to leap into re-inventing a wheel that might already exist, especially at the cost of "a week or two". Don't you think they already have something to occupy their time?
  • by SuperMallen (156287) on Friday May 11 2001, @11:11AM (#229319) Homepage Journal
    Although I can't say it's the greatest system I've ever used, PVCS offers a moderately simple web interface that should work across all OSes. Our non-developers use it to store their documents without too much trouble.
  • by grammar nazi (197303) on Friday May 11 2001, @12:38PM (#229351) Journal
    I have to start a new thread for this comment because _every_ comment that I've read has failed to mention the following solutions.

    As a systems engineer for a gov contractor, I needed to make a survey for documentation revision control software. Due to my CS background, I immediately thought about CVS, sourcesafe, and other source code revision control packages. The source code revision control packages were not up to the task of documentation revision control. Since systems engineers deal with requirements, and requirments are stored via documentation, every requirements analysis package comes with documentation revision control software. These packages also help to create documents from templates and databases. Depending upon your needs, these documents keep track of customer requirements from concept through delivery/installation, into maintenance.

    There are many systems engineering tools that handle requirements analysis in various ways. Many of them work with MS Office (prolly what your writers currently use), and have built in versioning control. My best source for information on these tools was at the INCOSE tools website [incose.org]. This sites lists tools and checks them for the following features...

    Store standard document outlines - used as starting points? User definable templates or modifiable?

    Produce architecture views from functional and object oriented (OO) perspectives? Examples: WBS, functional , physical, data flow, state diagrams

    Support various physical architectures? (View from a number of levels, Black box, Rack, circuit board, chip)

    Enable tailoring to specific standards and requirements, IEEE, ISO, MIL-STD?

    User friendly & menu driven (drag and drop capabilities)?

    Support a single user or multiple concurrent users?

    Input document change / comparison analysis

    Visibility into existing links from source to implementation--i.e. follow the links.

    History of requirement changes, who, what, when, where, why, how.

    Baseline/Version control

    Access control (modification, viewing, etc.)

    . Support of concurrent review, markup, and comment

    Multi-level assignment/access control
    Plus many more features.

    It is my opinion, that the following packages are up to the task:

    Cradle

    Doors

    rtm

    rdt

    Caliber rm

    If you go the page that I linked, it provides an in depth review of each of these tools plus many more.

  • by MacGabhain (198888) on Friday May 11 2001, @11:12AM (#229357)

    Microsoft Visual Source Safe.

    It stores versions, has a nice, friendly, Explorer-like interface, and runs on windows. Sounds like that's all the management wants. As long as they don't want to branch documents (which I recall being a bit of a bitch), they should be fine.

    (All of this with the note that I'm *pretty* sure that VSS handles binaries alright, even though it may not be able to do such things as diffs, even on files in a proprietary format from it's own company.)

  • by dSV3Hl (215182) on Friday May 11 2001, @11:16AM (#229373)
    There is a product called DocsOPEN made by Hummingbird I beleive. We use it at my office. It is WELL worth working into, and it integrates into almost everything windows. There is also a web interface for it called CyberDOCS.

    Basically, instead of saving your files to a drive, Docs comes up and asks you to fill out a form. The file gets saved somewhere mysterious, the data goes into a serachable database, and you get on with your life. Later you call it up by searching for it, and you can add a new version when you save it. It's pretty neat. However, it is hard to get people to use unless you beat them over the head.
  • by Philbert Desenex (219355) on Friday May 11 2001, @11:53AM (#229376) Homepage

    I used PVCS at my last job. My group developed and deployed on Solaris 2.6, even though almost everybody had NT boxes on their desks. We chose to use the Unix version of PVCS, which nominally ran on Solaris, but actually didn't. It actually only ran on HP-UX. We ended up with a really half-baked system where HP-UX machines running PVCS and our development machines NFS mounted a partition served by an Auspex NFS server. We'd log in to the HP-UX machine, set DISPLAY to desktop machine, and check-out into the NFS-mounted partition. Then, we'd log in to the Solaris development machines to develop, compile and unit test.

    PVCS for Unix is an absolute and utter mess. DO NOT let yourself be contaminated by the bug-ridden and awful terror that is PVCS. The GUI (Java app) is a heinous, bug-ridden piece of excrement with incredibly poor user interface. The GUI is slow, and has so many human factors problems that developers occasionally checked-in files in the wrong directory. The GUI doesn't do a good job of mapping "archives" to directories, and it doesn't map from directory to "archive" at all. This leads it to offer you a selection of "Makefile" archives, and you get to choose which one. You must understand the internal structure of the PVCS archive directory tree to choose the right archive. PVCS seems to think that all files have an "extension", whatever the hell that is, and if you have files (like "Makefile") that don't have an extension, it won't expand RCS keywords ($Id$, etc). The back-end is equally buggy. We had a more-or-less half time PVCS administrator, whose job included deleting lockfiles that PVCS would occasionally leave around.

    The company I used to work for chose PVCS for two public reasons: (1) it's nominally multi-platform (we found out that it isn't, Merant only claims it is) and (2) it had really, really elaborate management interfaces into the bug lifecycle. This makes managers happy, but leads to lots of ugly "WTF do we do with this bug report?" meetings at the end of a development cycle, the day before a release.

    I strongly reccomend you avoid PVCS.

  • by Ultimo (237838) on Friday May 11 2001, @11:14AM (#229387)
    Why not use HTML? I've been using HTML for years for all of my documentation. It works perfectly for a cross-platform manual accessable from anywhere.

    If you need powerpoint-type presentations, Flash [macromedia.com] is easy to use, fast, and readable on nearly all modern browsers. You can even generate it with PHP [php.net] or PERL [twoshortplanks.com].
  • by GeneralEmergency (240687) on Friday May 11 2001, @11:20AM (#229391) Journal

    If you need an easy to use UI, take a look at Xerox Docushare [xerox.com] or perhaps if you want to lean toward groupware look at Amphora [amphora.ee].


    "A microprocessor... is a terrible thing to waste." --

  • by kuhneng (241514) on Friday May 11 2001, @11:26AM (#229394) Homepage

    Check out TortoiseCVS from the CVSHome [wincvs.org] website. It's an add-on to Windows Explorer that adds status dependent color shading to CVS controled directories and context sensitive commands to the Explorer file menu. Comes with a bundled SSH client for secure tunneling.

    Easy to install and VERY easy to use, and no, I don't have anything to do with the project. I just use it.

  • by CoachS (324092) on Friday May 11 2001, @11:14AM (#229429) Homepage Journal
    Most major word processors include version control, comments, revision history and so forth. A major issue facing law firms these days is making sure that all of that content is removed/turned off before submitting electronic documents to the other side.

    It can be very embarrassing to have all of the private comments revealed to the other party when you didn't realize there were there. Increasingly firms are checking for these things as well.

    Word 2002, from the Office XP suite, includes a Security Tab on the Options settings. In there you'll find a Privacy section which gives you checkboxes for things like deleting personal information on save and "Warn before sending, saving or printing" a document that has file revision tracking turned on.

    -Coach-

  • Two weeks, one full time developer: $10,000.
    Two weeks, one office employee: $600.
    Five weeks, 3 part-time developers: $59,000.
    Q4 earnings time, the look on the boss's face: priceless.

    There are some things money can't buy. For everything else there's Corporate Mastercard.

    --
    "Fuck your mama."