from Hacker News

How do you deal with changing document versions?

by rashidujang on 6/21/18, 10:38 AM with 7 comments

At my company, the functional specification documents of the system is kept in a server where new additions to said documentation would result in a new version of the document being uploaded with a 1.x version being incrementally added to the file name. This results in a messy folder structure and redundancy.

However, most of the people who need the documentation aren't developers nor necessarily even that tech-savvy.

What are some ways similar problems are combated in your own workplaces?

  • by acutesoftware on 6/22/18, 1:51 AM

    Any sort of versioned online wiki tool is better than word documents with filenames - this can be your own wiki, or sharepoint or Drive.

    Non tech savvy users can read the page to see the latest version, and others can track through history if they need to.

    We've had success doing smaller projects completely on trello, though it isnt really a wiki tool, you can force it by having a single top level card with all the feauture requests linking to individual cards to see the progress.

  • by JanisL on 6/22/18, 4:28 PM

    If a document is super important we make sure that it's only worked on in a system that support some form of version control. But that's fairly easy for us because we pretty much all are comfortable with Git. In the cases where people simply won't learn Git I find going with some sort of web-based version controlled documents is a massive win.

    Whatever you do avoid situations where people email around attached documents with various changes, set strong expectations that emails like that are not to be used. Most of the troubles I've encountered have been because of the inevitable merge conflicts and associated hassles from divergent documents that occur with email attachments.

  • by matt_the_bass on 6/21/18, 11:21 PM

    We use git for all our code and svn for our electrical design files. These work reasonably well for engineers but not for non-engineers (sales, marketing, admin, corporate). We tried using svn with word processing files (word and open office). This generally sucked.

    So we’re tryig something new: google docs. Recently we migrated our file server to google drive and have been moving from open office to google docs.

    Google docs works great for light weight version control of non-engineering documents. Just name a revision as x.x.x and only distribute named revisions. This obviously only works for documents with a single “branch” but for 99.9% of our non-engineering version control needs, this works GREAT!

  • by digikata on 6/22/18, 5:37 PM

    If you just need a little duct tape hack for your situation, you can setup a script to scan the folder and point some html page of links to your latest doc set. Could even as simple as a generated static html file named to appear at the top of the folder or folder tree in a known place.

    Communicating and agreeing on some commonly understood system is typically a more effective factor than the tooling.

  • by executesorder66 on 6/21/18, 11:00 AM

    We use Confluence [0]

    If you can't afford the license, I think any self hosted wiki software will do the trick. Try [1]

    Using Word documents is terrible for various reasons.

    [0] https://www.atlassian.com/software/confluence [1] https://www.mediawiki.org/wiki/MediaWiki

  • by dirktheman on 6/21/18, 2:29 PM

    I guess you could find some way to convert Word documents to Markdown and keep version control using Git, but for non-tech-savvy users I assume that's going to be a problem...