Forgot your password?
typodupeerror
News

Version Control for Documentation? 296

Posted by Cliff
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."

This discussion has been archived. No new comments can be posted.

Version Control for Documentation?

Comments Filter:
  • I don't think "computer illiterate" users is the issue here! MS Word docs are binary, so you can't just do a diff on successive versions. Also, DOC files use structured storage, so there is always the possibility that the contents will get rearranged within the file itself. Most CM tools treat binary files as blobs, not bothering to diff them at all. THis causes bloat in the repository (unless the files are compressed.) To successfully diff 2 Word docs, or Excel spreadsheets, or BMP or GIF files, etc, you need a diff tool that knows that particular file format.
  • by Anonymous Coward
    I used to work in a big defence / aerospace company where I got in touch with Unix (SunOS). There was a wonderful text processing software : Interleaf (with Lisp Macros !), where you could get two equivalent versions of your text files : either in a binary (.doc-like) file or in a ASCII-based marked-up file (this was processable with sed or Emacs macros). an ASCII-based text file is "naturally" manageable with VCS or RCS (while a binary-file, like Word produces, is impossible to process) does anyone know what happened with InterLeaf source code ? (the beast should be portable to many open-source Unices)
  • by Anonymous Coward
    Search for "Doors", a software package that is aimed at Requirements Management. (I think the company name is QSS, but I'm not sure.) Doors features a differ for Word Docs, and it either acts as a repository in its own right or a front end to a repository. Not sure what the pricing is like, but it might be worth it, just for the Doc management stuff.
  • 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.
  • Or rather, Subversion will be CVS done right, when they get it ready for public consumption.
  • 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.

  • There are GUIs for CVS for many operating systems (including Windows and MacOS) at cvsgui.org.

    jCVS [jcvs.org] is also a decent graphical CVS front end and based on a cursory look at CVSGui/WinCVS, it runs on far more platforms and provides a consistent interface across them (it's written in Java, so it should work on pretty much anything with a good VM and set of class libraries). I used to use it all the time on Windows and now I use it all the time on Linux, so I know it works well on at least those two platforms. I think you can also set it up as a servlet so that users can access it from a web browser.

    This isn't to say that CVSGui isn't a good program, I'm just pointing out another UI option.

  • 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 @02: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.
  • by booch (4157)
    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 @12:19PM (#229209)

    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 @12:51PM (#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."
  • by Ctrl-Z (28806) <{tim} {at} {timcoleman.com}> on Friday May 11, 2001 @12:20PM (#229226) Homepage Journal
    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 @12:25PM (#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.

  • Others have pointed out in the other VSS suggestion threads that VSS has integrity problems. I've worked with VSS for several years, and it still has these problems. The repository corrupts itself on a daily basis when you start storing anything big.

    I would recommend you use anything except VSS. Regardless of your OS religion, userland preferences, editor choices, or revision control system, your goal is to be able to track change. The usefulness of your system is null or negative if said system cannot be relied upon when you want to revert to an older version. Relying on VSS is tantamount to "backing up" by dump(8)-ing to /dev/null.
  • 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 @12:43PM (#229249)
    CVS done right. [tigris.org]
  • The ease of use issue need not be a big problem. You can throw together some quick VBA code to modify how MS Word opens and closes documents, to handle transparent checkin and checkout operations. The same is true for Excel, and (I believe) PowerPoint. Using the same technique, you could also switch the default file format to RTF for word. Thus the documentation folks would not even be aware of the versioning, unless they attempted to open a locked file.

    RTF can easily be handled by CVS, so there would be no problem there. If I remember correctly, Word supports embeddable data fields, and this can be used to synchronize document versions with software versions, as well as handling the various scheduling and life-cycle data that the docs folks need. For Excel, this data can be stored in standardized grid locations that are outside the displayed or printed boundaries defined. I don't know about PowerPoint.

    If the docs department has not already done so, they would have to make use of "master documents" to control the full publication, so each writer, illustrator, etc., is working with a relatively small file that covers no more than one chapter or section of a document. This is the only way that file locking will work successfully.

    One person in the docs department would have to learn WinCVS, or some other GUI front-end, to be able to resolve the occasional problem (or they can just contact your CVS person). There would also have to be a few standards imposed, such as closing a file when leaving for the day. But these are very easy to implement. You could even use VBA to force a save and file close after x hours of inactivity and generate a message or email to the docs writer to explain what happened.

    I strongly advise against using a separate version control system for software devel and tech docs, since this would only complicate coordinating the right software versions with the corresponding tech docs versions. If you make it transparent, then each tech docs professional is doing things the way that they know how, but the underlying mechanism is doing what needs to be done to implement proper version control, and synchronization with software versions.

    If your company is on a tight budget, this is the way to go. Not only can you resolve your problems with a minimum of expenditure (a day or two of programming time), but you can also sell your VBA code to other companies with the same problem (or to one of the companies that specializes in such things), or donate it to become part of the CVS repertoire.

  • A couple years ago, we put forth a huge project to create an FDA-compliant document control system. We called it DCMS (document control management system). It was a strictly internal project, but I was the main developer and one day wanted to make a GPL'd version for the public.

    Among the features: search criteria for many attributes, including indexed text-lookups (by using the unix "strings" tool). There were two modes.. One was "browser-mode", who could only search for "released" versions of documentation and click on a link to download the document. The other was "editor-mode", which required a secured login. From here you could browse any version: draft, approved and or released. At which point, you could "check-out" a document, which would lock it under your name and save a copy in your work-space, which is on a samba/nfs-exported directory (Your X drive in windows). It was su'd to your name so that only you could edit it. Documents were categorized into classes, subclasses, and document-types (product/project/quality.. Then product-name, project-number. And finally, doc-type which was technical spec (TS), functional spec (FS), requirements (RQ), etc..). Each document was given an auto-incrementing document number for unique identification.. So a document name was "DCMS_FS_00079.doc". Managers controled the doc-categories and creation of new documents.. It became a full time position, but FDA requirements are pretty strict.

    When you were all done, you used the web to check it back in, which created a new daft version and allowed others to check it out.

    authors would submit requests for review of documentation to manager-users, who would ultimately "approve" and later "release" a given version (making it available for public viewing).

    Our first version used "clear-case" as the version control (which allowed direct URL-links to files, instead of explicit extraction from RCS), and as the meta-data storage repository (since it had it's own searching engines). We made heavy use of Perl and at the time Netscape-server.

    I was in the process of rev-2.0 which would use Apache, Perl, RCS and MySQL and ideally be open-sourced, but our company took a major turn which seized all projects. However, DCMS is still fully running today (under different management), and aside from the performance issues of the clear-case dependencies, works great.

    If I had the time, and if I were to do it today, I'd use postgres (for roll-back support), flat files (no real point to RCS if you let the DB do everything), Apache and maybe something like zope with python (though I'm still partial to perl).

    -Michael
  • (Yes, that means everyone you know should be running linux as well.)


    I thought I had made peace with the FreeBSD users' group after all these years. Now you tell me that I have to start the flame war anew. You must be one of those twisted vi and tcsh users!
  • by TheCrayfish (73892) on Friday May 11, 2001 @12:17PM (#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].
    ---
  • An extension of this, at my workplace, the network drive had folders with names like "Drawings from Joe-If you are not Joe do not put drawings here" and "Parts lists etc.- Ask Bob if you need help with these"
  • Two possibilities.

    Since all of your stuff is M$ office stuff, use Exchange server. It will keep track of who made edits to files, when they made the edits, and will only allow one user to make edits at a time. Combine that with or have that indepent of SourceSafe and as long as you backup your environment with regularity, you're golden.

    We use both without our company (yea, small dev firm that uses microsoft products), but they work well and we have yet to have any problems.

    I see that people on this thread have claimed that SouceSafe has "eaten" some of their documents... can you honestly believe the word of someone that uses the technical term of a file being "eaten"?
  • by Speare (84249) on Friday May 11, 2001 @12:26PM (#229273) Homepage Journal

    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.

  • Flash as a replacement for powerpoint. You're defenitely not an office worker. It probably has been 20 years since you last saw one :-)
  • Since you are in a Windows environment with MS Office documents, Microsoft's SharePoint Portal Server [microsoft.com] is exactly what you're looking for.

    Basic features are:

    Search Engine

    Subscriptions

    Categories

    Document Versioning

    Collaboration

    IFilter support (to support more that Office docs)

    There's a trial version available to test it out.

    ÕÕ

  • by iguy (89163) on Friday May 11, 2001 @12:46PM (#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.
  • ...several commercial solutions for something like this. If you want to save money, you should train your people on CVS. If you can affor it, you might want to look at Documentum or another document management system. Those systems are a bit less intimidating than version control tools targeted toward developers.
  • Don't spend your time putting in place a version control system an idiot can use. First of all:

    1) An idiot won't be able to use it properly
    2) Having the technology available will only make them seem (and probably feel) stupider

    First of all Word and Excel aren't that easy to learn. You can type up and save a document no problem, but learning how to do precise formatting tasks is something that takes good doc people a long time to learn how to do properly. Furthermore, doc people have to understand the thing they're documenting, which is not that much easier than writing the code in the first place, for lots of projects. Thus it's a fallacy that doc people aren't technical enough to learn good version control.

    Secondly, CVS is pretty easy to learn. 99% of working with CVS is two commands: cvs update and cvs commit. Even assuming you don't go with one of the many adequate-to-kickass gui clients for CVS (my fave: TkCVS, maybe even in Windows), your learning curve for what most of the doc people have to know is pretty low. You can send 5% of the team to a class or buy them a book, there are ALWAYS people who want to know just a little bit more about the system they work with, and those people can be the gurus for the rest, who really just want to write doc.

    Finally, if you try to implement version control without SOME education about what's going on behind the scenes, you will have lots of minor tragedies. Version control isn't perfect, and you do not want people to think that it is, or they will lose even more of their work when it's not. You want them to know things like: If it's not checked in, it doesn't really exist. Always do diffs see you can see what changes are actually going in when you merge a new version. Let your teammate know when you have to work on a document they already have checked out, or you'll clobber each others' changes.

    These kinds of things are obviously harder to learn than the mechanics of actually using the version control system. They have to be, or the coders I work with wouldn't make these mistakes so frequently. Since you have to spend some resources giving your doc department this kind of education anyway, you might as well spend some time teaching them how to use a good doc system as well. CVS is truly one of the best.
    --

  • Most people aren't so dumb that they can't. Many are so scarred by their experience or learning all of the wierdnesses of Windows, that they don't want to through it again.

    If you can come up with a simple start-up situation for them (this is how you save, this is how you restore, and this is how to get a not-so-recent version), then they'll be happy.. When they get used to it, and want the more complicated stuff, then you can teach them that part of what the system is capable of doing for them.

    Just don't expect them to learn the whole thing from get-go, or they'll run screaming. Teach them what they ask for, and then shutup.

    For the curious few, you can teach them more (as much as they're willing to learn at the time). They'll be happy to teach that their colleagues when the time is right. Just be careful with the dangerous stuff ("this is how to delete an entire branch ---- oops.").
    --

  • Document management is not just keeping track of a particular versions. This is an important part, but users also want to:
    • Publish documentation in a common format (think HTML or PDF) even though it is authored in multiple formats (Word, Powerpoint)
    • Text search, you all use Google, Altavista etc. You need to have the same tools for your document management
    • Messaging integration, you may want to be notified when you have to do something, such as review a document
    • Security control
    • Web access to the inteface is nearly mandatory, why would you want anything else :)
    • You want to be able to annotate the content of the published documents [zezame.com]
    • You want to be able to integrate with it through standard interfaces
    Commercial systems to investigate:
    • Reasonably inexpensive and easy to learn, eRoom.
    • More complex, expensive and more capable, Expedio and Intra.doc! from Intranet Solutions
    • Evil Empire verion, Tahoe
    • High end, Documentum


    • I have designed and build several of these type of systems. You generally don't hack together a document management system in a weekened. If you think so, then research your users requirements a bit further. :)
  • We faced a similar problem at my company and ultimately chose Docushare from Xerox. Nice easy to use integration with Windows (ack!) Explorer or a parallel web interface.
    Engineering and Prof Svcs continue to use cvs for source code control and Docushare for all documentation that isn't part of the product itself.

    http://docushare.xerox.com [xerox.com]

    -Hal Incandenza

  • 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?
  • I work in documentation. I've used a bunch of different version controls systems and performed needs analyses a few times when companies I worked for were switching over to "integrated" systems for development and version control, and someone decided that docs should go along for the ride.

    Before you decide what system to recommend, you *have* to know what problem you're trying to solve. If the documentation is a mess, is it because you have a million old version sitting on your intranet, or even in binders? Is it because nothing is indexed so you cannot find the information you need, even though you suspect it exists? Is it written for a mess of different audience types? (PHBs, engineers, end-users, marketing?)

    If any of these are the root of the problem, any type of version control is not the answer. What you need is a document repository. This can take the form of an intranet (MS's server happily displays office docs, though it will eat tons of drive space) a shared directory, or even a designated bookshelf where all the docs go.

    Training whoever produces these docs on whatever system you use probably won't help, because it sounds like the real issue is that they haven't grasped the whole process of information management, notwithstanding whatever tools you provide to them to make that easier.

    So, send these people to an information architecture course, or if that doesn't help (since there are a lot of not-super competant people working in docs, I hate to admit) get them an admin or a student co-op whose sole purpose in life is to keep track of these things. It may be a longer-term cost that telling them to use CVS, but it will actually work. Trust me, the problem isn't that they lack the tools. Good documenttion can be produced by quilting, if you're product cycle is long enough. The problem is that your docs manager (if you have one) doesn't understand how to manage information and keep it current. You should get a new one, or send the one you have to training, if you think they're redeemable.

    If you are required to come up with some kind of software solution, here are some pro's and cons of systems I have used:

    CVS: My personal favorite, I've used it on both UNIX and through a Web front-end. Pros are that it's incredibly flexible, free, and easy to migrate from if you switch to another system later. Cons: You can't diff unless it's a plain text file, and if you throw a lot of office or Frame documents in there, you better have a *lot* of disk space. Plus, we had a lot of resistance from people who had never used versioning. It is surprisingly hard to see the benefits, for a lot of people. We constantly had people writing over files, checking in old verions, and causing all kinds of havoc. Plan on having someone administer to this kind of thing if your user base is how you described it.

    Visual Source Safe: Stay Away! I've used this in conjunction with an MS intranet server, which carried a large mixed bag of html and office documents, mostly posted by folks with very little technical knowledge. It was a mess. We ended up devoting a lot of our time just administering the thing, which is not as easy as microsoft likes to claim. and slow Slow SLOW. Sometimes I could hardly believe it. On the plus side, you can visually diff office documents, if you have the patience.

    StarTeam: This system is weird. Docs went along with the rest of the engineering group on this one, but it will seem awkward for people unfamiliar with versioning, and it's very quirky. Its collaborative features, like file locking and bug tracking, are really awful.

    And remember, version control makes a lot of sense for code development, but not usually as much for docs, because:

    • code is generally much more of a collaborative effort. It is rare for several people to work on the same file in docs.
    • unless you're documenting in native HTML (which doesn't sound like the case) you can't do diff's with most systems, and binary files eat disk space like you wouldn't believe.
    • Most word processing software has some kind of native versioning and locking, which often gets totally foobar'd when you try to integrate it with another "source control".

    There are a lot of documentation consultant companies out there, some of which are very good, and most of which will happily outsource your whole doc department. Consider that option too.

    Good luck.

  • I know it's not stable/feature complete yet, and it doesn't quite yet compare with MS Office, but it does have it's own set of benefits (opensource, etc.). And if you could switch teh "windows users" to OpenOffice (which could probably import most of their word docs, etc.), then you could start them using the XML format -- which then could be saved in CVS! Then you have the problem of uploading/etc. via cvs, which would be best solved with an OpenOffice plugin, but in the mean time one could use WinCVS, which I feel is very easy to learn. HTH, -Dan.
  • We use perforce here at work. It's got client binaries for *nix and Windows, and using it is no harder (once your 'view' is setup) than typing "p4 edit {file}" or "p4 submit {file}". Breezer. Cost is, well, I'm not sure, but I just use the tools, I don't really buy 'em. :P Check Perforce [perforce.com] for more information. It works well, we've never had problems with it, so based on that I can endorse it.
  • Corporate documents have much different needs than programs.

    Well put. MS word has facilities for versioning, specifically the version number, approvals/proposed revisions, and other stuff. I haven't used it extensively, but a google search will probably turn up a tutorial or ten. You could also invest in one of the multitude of books about MS word on the shelf at your local B one of them must discuss versioning. Lastly, check out the commercial offerings posted elsewhere here.
    -bluebomber

  • by SuperMallen (156287) on Friday May 11, 2001 @12:11PM (#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.
  • The marketing jargon is hideous and the product overpriced, but Livelink does have nice version control / check-in/check-out features, among other things.

    It works through a web interface, although one that's rather prone to working well only with IE, ugh. I'm not sure how well it would work with Linux boxen -- I'd ask, but then do a large amount of testing to be sure it worked properly.

  • I wish I'd seen this sooner. I'm having the same problem with CAD documents - large complex binary files, across many computers on a network. And then I need to at least give out unique numbers, be able to find given files reliably, and track revision letters.

    In anyone has any advice relating to this I'd greatly appreciate it. Currently we have an old proprietary system that we seem to not have the source to - even though it was made in house.
  • We used WinCVS [cvsgui.org] at my last job. Now up to 1.2. Works decent, at my last job even the engineers weren't all that technical (gee, wonder if that's why we havent' made any money) and works OK.
  • Having consulted on site for a client that used Documentum at a number of levels I can say that it is:

    • Big
    • Complex
    • Expensive
    • Difficult to manage
    At least it was with version 3. Version 4i may be better, but it didn't work when we wanted to test it.

  • Why would someone want to implement that?

    Isn't it okay for people to randomly change business specs on the fly during a project so that there is a near zero chance of success? =P

    Plus I like to dig through 30 different docs with different names modified by different people with insanely long filenames.

    Gotta go someone just changed the spec without telling anyone again...

    Long live document anarchy!

    =)

    E.
  • One hack type of solution that I recall from the world of dos and windows what a generic NON-MS database with fileds that had the document name in it as a character field. a widget on the screen could call up the MS doc by file name, and launch word or whatever.

    In the original, the file was a medical record sort of thing, so it was a doc with a name made up of pateint ssn number, doc ID, and a time/date string. The file names got stored in the db, and the db could launch w to open them via a command.

    The only thing I could think of is maybe a widget or macro in word to save the current date/time as part of the file name, along with the user ID, so that as soon as word opened the file, it would be saved with the new file name with the updated data in the name.

    Wait, as part of the command line, you can set it up to copy the file to a new name with the propwer date and time info in the name, then feed the string so you have a proper record of it in the database, and then open it in your word processor. This maintains an audit trail, since everytime a doc is opened, a copy is made and saved. You could also include a delete option for just for folks just looking around.

    So this is not to hard to do via the database of your choice. Although you better have a lot of drive space for the clueless. A really messy solution, but if you have space to waste, semi-workable. This would work for in house, not webifried.

    You would have to add a layer in there some place for converting to web format, depending on the word processor you use.

    Check out the Vinny the Vampire [eplugz.com] comic strip

  • Just noting in passing,

    That the version tracking can take palce inside the document, or outside the document. Version tracking can be engineered outside the document if you have many types of data and documents. Then you will need a database to control the varios parameters of the documents such as file names, number of copies, who has access, etc. This can be a problem, but it is not outrageous, depending on the capabilities of the technology at hand. I would think ity is certainly within the capabilities of perl and the table technology of your choice.

    Check out the Vinny the Vampire [eplugz.com] comic strip

  • Hrmmmm...

    Doesn't software still require all of those things? I think we call it a System Change Request (SCR) or just Change Request (CR) process.

    We have implemented it so that if our customer requests a change (software, user manual...) then it goes thru the same process. Docs also get stored in the same tool as source code. Goes back to the theory of "one process, one tool, many products".

    As far as making simple so that non techies can use it...ummm...I have two recommendations (facts really). 1) non techies are going to have to step up to the plate and use the tool. 2) make the process such that it can be adaptable and easy to use (hold their hand step by step).

    Pretty soon you will be at CMM 3.

    dman7
  • for document management - it's okay for that purpose, but quite inflexible for document sharing on an intranet. I've found myself frustrated with this inflexibility quite often. (e.g. you can't easily have a user-friendly index.html pointing to the documents you want to share in a directory). Haven't tried the version control feature.
  • by grammar nazi (197303) on Friday May 11, 2001 @01: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.

  • Believe it or not, that's the combo we use. Works well, and LyX even shows the expanded $Id$ on the front page...

    -mi
  • by MacGabhain (198888) on Friday May 11, 2001 @12:12PM (#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.)

  • Honestly for simple, remotely accessible, and end user friendly document management, I would recommend using SharePoint. Downside is it won't run on Apache which sux (Only IIS), but if you take a look at the features, it will likely have what you need and more. I didn't catch the number of documents you are attempting to organize, so if you need batch processing then it'll likely require some simple VB scripting. I've got a copy of the release version, which ships with Office XP, and will install on a private site on one of my Internet servers if you want to take it for a spin. Before changes jobs, I was the Lead Beta Engineer at MS for this product (Used to be Office Web Server before the fancy name). It can export lists to excel files with the click of a button and can easily be modified to add features or remove features you don't want. It's all HTML/ASP and works as an "Out of the box" solution in many cases. If you are keeping previous versions of documents and want them listed in archive fashion, some SQL queries must be modified or added. If it's more involved than what SharePoint is capable of, I would recommend a custom built app from an ASP or outsourced developer (Keeps things on schedule and prohibits unnecessary updates). Email me ben@optisonic.net if you want a demo, need more info, etc. Regards, Ben
  • If you don't find what you're looking for, the aerospace world has some excellent best practices for documentation configuration management in more NASA specifications than I care to think about. If interested, email.
    --
  • by dSV3Hl (215182) on Friday May 11, 2001 @12:16PM (#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.
  • Y'know, there's a number of different options here, depending on what you're trying to do. The problem is, you talk about the format, but not about the real issues. "VCS" is actually a pretty easy term to throw around, but not quite so easy to lock down when you're talking about documentation. That being said...

    First, if all you're after is the ability to accept/reject changes to documents, then the simplest solution you want is to turn on the "Track Changes" option. You can leave the master "track" on, then either display or not display changes in either printed or written form. Also, you can selectively accept those changes to the base master document. All changes are also tracked by author, time/date, etc.

    Second, if what you're after is protection of source files, then you really are going to have to implement a VCS for your writers. I've used a number of them, and fundamentally, none of them are easy for non-technical people to use without training/etc. Perforce and Clearcase both work reasonably well for cross-platform doc checkin, but, well, they're not exactly the easiest thing in the world to use. A simpler solution might be to have a decent server, and have it incrementally back up _every_ change to the doc section. You'd be surprised how easy that makes it to roll back changes. If you're also willing to be a little anal in the server setup about who owns files, it should become fairly easy, fairly quickly to resolve ownership/etc. issues.

    Third, I noticed you were also talking about PDFs, and how the documentation was difficult to access. Two points here. The first is that you probably should stress to much about storing output (PDFs, generated HTML) in VCS, rather than storing source files. If you can store source properly, storing generated doc (PDF/HTML) becomes _very_ easy. The second is that making your documentation easy to access is an entirely different issue from puttingg it in a VCS. That's a matter of putting together a clear, logical structure that makes sense.

    As a case in point, one of my clients about a year ago had _all_ of their documentation stored in VCSs. Their problem was not that it wasn't protected - it was that, in the course of 2 mergers, and going through 4 different writing teams, they'd _lost_ their documentation source. So before I could write word one, I had to go find the docs, sort out the doc structure, and get everything so it could once again be found and accessed.

    One relatively easy-to-use structure that I've seen involved differentiating the source vs. output, and making the output available on an internal webserver. Output was automatically regenerated on a regular basis (simple scripts took care of most of it, or you can use the monkey model, and do it manually), so it was available to the entire company. Those people who needed to mess with the source files were taught how to use the VCS.

  • by Philbert Desenex (219355) on Friday May 11, 2001 @12:53PM (#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.

  • My company - a large Telecom equipment maker - has begun to shift development and product documentation from a proprietary system, to a combination of ClearCase, a popular commercial version control system, and MS SourceSafe.

    For ease of use and based on cost I'd have to say, for your application (as much as it pains me) Microsoft SourceSave would be a good choice.

    Just my 2 cents
    --CTH

    --
  • by Ultimo (237838) on Friday May 11, 2001 @12:14PM (#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 @12:20PM (#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 @12:26PM (#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.

  • I'll put in my two bits for LiveLink as well. We're just rolling out where I work but already people are loving it. Our Documents and Publishing department no longer has to worry about multiple versions or not knowing who's in the locked file or any of other large numbers of problems they have. It's been an absolute godsend to them. Now here in support we're starting to use it for all of our documentation so we can track what changes were made to what documents when and by who, so if someone puts in something stupid we can string them up by their b@lls :) It's pricey but a great product =)
  • You could also try the M$ solution:
    SharePoint [microsoft.com]

    Art At Home [artathome.org]
  • Although it isn't documentation, and gets used for somewhat different purposes, law firms have a similar need. They don't look at it in terms of CVS, however, and the documents they deal in tend to evolve more slowly, but also pass through more hands in general. Furthermore, particularly with documents relating to negotiations, version control AND change tracking are an absolute requirement. Just the hint of a notion that a firm is not able to know precisely what changed between one draft and another can result in a catastrophic loss of credibility when negotiating.

    They refer to it as "document management." While a big part of that is also a matter of FINDING the documents (think of alllll that paper), the most challenging part remains tracking changes. You might want to contact a company that I've dealt with in the past who makes a fantastic system (sorry, it's not open source) called iManage. It's overkill for what you need, but you may be able to show them another market they haven't thought of, and develop something with them to suit your purposes.

    And no, I don't work for iManage, have any stock (if they are traded, even), or anything of the sorts. I just really liked the product when I helped implement it a few years ago, and know it does a good job.

  • We use WinCvs [cvsgui.org] and Chora [horde.org] to version control both source code and documentation. In fact, it is because we were using Chora as a web interface to our documentation that I uncovered a bug a month or two ago affecting the handling of filenames with spaces (like Marketing Proposal 1.doc) that we often see in documents created by non-programmers. I fixed the bug myself and contributed the fix back into the Chora project, so you shouldn't see this problem in the latest version of Chora). I've packaged recent versions of Chora into zip files - available for download here [pixeldate.com]. (Use Ctrl-F to search for Chora on the page)

    I have to admit, though, that while the non-technical people at our company have managed to learn how to use CVS, it was not without a lot of struggle on their part. Maybe SourceSafe or Perforce would have been a better choice. Even so, what we have now works and people have become familiar with it, so I don't think we'll change.
  • At work, we *used to* have a few pockets of SourceSafe... now everyone uses StarTeam. It's pretty decent for anything, whether it's text or binary, and the integration with NT domain user authentication is nice, too.

    Sometimes it really sucks ass and eats a file or shows you the wrong status, but for the most part, it's great, and it's much more prone to error on the user side than it is with the client or server, and in most cases we have artists, not writers or programmers to blame for that.

    --

  • This is something of a "me too" post, but in this case it's warranted; it can't be said too often -- run screaming from PVCS. The above author's post is glowing recommendation of PVCS when compared with what I'd tell you about it.

    Everything he says is true, except we actually did get it to work under Solaris (if you can call what it does "working".) It comes with a set of command line tools that were apparently first written when DOS was new and a GUI that is fitted to the system badly on top of them. You'll find that if you use the command line tools exclusively, you'll confuse the GUI, as the command line tools don't have any concept of the GUI's "folders." So those you'll have to edit by hand. However, you can't limit yourself exclusively to using the GUI, as it's not functional enough and it's intolerably slow. Hit ctl-C at the wrong time when using any given command, and you've got to call an admin to cleanup the lock files it will leave behind.

    My favorite indication that the Intersolv developers have absolutely no Unix clue: The GUI is very windows-flavored. Run the GUI on a serious unix system, and it will stat each and every filesystem to build a filesystem display. Whee! Watch all of those automounts kick off! See the NFS traffic fly! Or simply go to lunch and hope it's done when you return.

  • a binary diff will result in a file larger than the two original files.

    That's not true. I used xdelta [berkeley.edu] on two ~180 MB binary files that were quite different, and it made a ~500K patch.

    Ryan T. Sammartino

  • folder action converts .doc to RTF, .XLS to tab seperated. They'll lose all macros and lose formatting and layout in Excel that way. Maybe not the best approach.
    -----------------
  • I was waiting for someone to mention Perforce. I worked with it once, and yes, it is expensive.

    The GUI interface is almost impenetrable (based on previous experience with SourceSafe and PVCS), so I wouldn't recommend it for non-techies.


    -----------------

  • 1) Switch to LaTeX

    2) Teach them CVS

    haha!

    I'm only partially joking however. That would be SO NICE.
    Regardless, CVS handles binaries (albeit inefficiently) and isn't that hard to use with wincvs.

    --jeff
  • If the people in your company don't understand how to use CVS, or even what it is, then they really shouldn't be demanding that their documents are kept in an orderly fashion.

    Don't bother trying to get an "easy to use" solution, which will take up valuble system resources just to run. Anything worth doing can be done from something simple like CVS.

    If they are really so dumb that they CAN'T learn CVS, well, its time to tell them that they are in the wrong field, and that they should consider a carrer in garbage collection or burger flipping. Tough love oughta get them educated real fast.

  • Most places I've worked have not leaned that heavily on document-control systems for things like that; there is the most up-to-date version and that's pretty much all you need. (I currently work in an environment where there is a huge document-control system, but I use it so seldom I have forgotten how to get into it.)

    You probably need to have someone in control over the mess, and if that person can manage a directory tree which is read-only to everyone but the archivist you could easily keep a "history" directory beneath each leaf and stick old versions down there (with filenames containing the date of the revision). That would give you lots of history and a ready means of re-organizing if you find a tool that lets you manage things more easily in the future.
    --
    Having 50 karma is an itchy feeling; I know I'll get

  • by CoachS (324092) on Friday May 11, 2001 @12:14PM (#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-

  • Cobalt makes the little Qube network servers, with something like 20 gigs of drive space, some RAM, and proc for under 2000.00. These boxes come with a document control and search engine software installed. They run linux, but I believe that the document control and search is proprietary. Might want to check it out at Cobalt Networks [cobalt.com] now owned by Sun microsystems.
  • by Magumbo (414471) on Friday May 11, 2001 @01:20PM (#229435)
    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."

  • I used to have a job as 'release manager' at a software development company. This company released sourcecode together with documentation on the sourcecode in MS Word/Framemaker files.

    The source code at that point was revision controlled in SCCS (yuck) but the documentation was not. Seems very much like your situation I guess.

    Putting the documentation in a CVS project along with the software itself would work pretty well, except that CVS will not do delta's on the binary files but will store each revision pretty much in it's binary format in the repository. This is not a big problem as disk space s cheap.

    Also, teaching people how to use some windows CVS client shouldn't be a big issue I believe. However, I've found in the past that people often *want* the GUI version first and within a few weeks are asking me 'so how can I use that command line version you're using'.

    Personally I like to teach people a few very simple things:

    • ssh into a Unix box
    • set up their CVS variables for them
    • make sure they check out/commit on a file system that can be mounted through SAMBA on their PC.

    • Imagination is more important than knowledge.

Mathematics deals exclusively with the relations of concepts to each other without consideration of their relation to experience. -- Albert Einstein

Working...