Everyone has their favorite mediums and places for project documentation. A sampling of what I have seen is
-Word in Visual Source Safe
-Wikis along PowerPoint in CVS and Sharepoint
-Wikis along with Word in Sharepoint
Word turns out to be a reasonable medium for documentation as long as when edits are made one turns on change tracking. I have only seen this done at one place that I have worked though, so I don't think most groups get as much value as they can by keeping docs and specifications in Word. PowerPoint as a medium for documentation and specification, at least in my experience, is a loser proposition. I find the communication power of PowerPoint low. It's a medium for entertainment, not engineering.
Wikis, as medium and storage, are an OK solution for documentation. About 5 years ago there was a lot of buzz about wikis and I was thinking that wikis were the future of documentation systems. I have not seen them deliver on their promise. Its harder to get people to contribute to a wiki, usually one person buys in and the rest of the team contributes when they are forced to. Since everyone owns the wiki, no one has any responsibility for the wiki with predictable results. Wikis also get disorganized over time and accumulate out of date cruft.
For storage companies seem to love Sharepoint. I don't see anything to recommend in Sharepoint. I suppose people can write code and create Sharepoint applications but people should have better things to do with their time. Admins can set security/ access restrictions on Sharepoint but why why why would any group want to place access restrictions on documentation and specifications? But groups do all the time. And then, like Wikis, its hard to find stuff in Sharepoint, but harder than finding stuff in a Wiki.
What I like to use for documentation are text based files in a version control system. I'm sure proposing a text based media format sounds primitive but it has the advantages that it is search-able with tools like grep and its also diff-able. Text based formats are also transformable so there are tools that can change text based formats to HTML which can then be published to a web site. Also there are tools to convert text to LaTex and then rather nice pdfs. For storage the most important thing is to put all documents and specs in one place. And if that one place is a version control system, then one can pull documentation for different points in time or different versions of a product. For specifications being able to do diffs on changes that are going on, to observe how a specification evolved over time, or to check who made changes is a huge time and fuck-up saver. As developers we all seem to have found value in putting code in version control systems. I don't make a strong distinction between documentation, specifications, and code. To me they are all product development artifacts that change over time. Dev artifacts that change over time defines what I want in source control.
Above I listed three documentation solutions that I have seen a various companies. Word in VSS worked the best and what I choose on my own personal projects is text files (Emacs org mode) or LaTex files kept in git. Infinitely more simple, less costly, and more efficient than anything I have used else where.
-Word in Visual Source Safe
-Wikis along PowerPoint in CVS and Sharepoint
-Wikis along with Word in Sharepoint
Word turns out to be a reasonable medium for documentation as long as when edits are made one turns on change tracking. I have only seen this done at one place that I have worked though, so I don't think most groups get as much value as they can by keeping docs and specifications in Word. PowerPoint as a medium for documentation and specification, at least in my experience, is a loser proposition. I find the communication power of PowerPoint low. It's a medium for entertainment, not engineering.
Wikis, as medium and storage, are an OK solution for documentation. About 5 years ago there was a lot of buzz about wikis and I was thinking that wikis were the future of documentation systems. I have not seen them deliver on their promise. Its harder to get people to contribute to a wiki, usually one person buys in and the rest of the team contributes when they are forced to. Since everyone owns the wiki, no one has any responsibility for the wiki with predictable results. Wikis also get disorganized over time and accumulate out of date cruft.
For storage companies seem to love Sharepoint. I don't see anything to recommend in Sharepoint. I suppose people can write code and create Sharepoint applications but people should have better things to do with their time. Admins can set security/ access restrictions on Sharepoint but why why why would any group want to place access restrictions on documentation and specifications? But groups do all the time. And then, like Wikis, its hard to find stuff in Sharepoint, but harder than finding stuff in a Wiki.
What I like to use for documentation are text based files in a version control system. I'm sure proposing a text based media format sounds primitive but it has the advantages that it is search-able with tools like grep and its also diff-able. Text based formats are also transformable so there are tools that can change text based formats to HTML which can then be published to a web site. Also there are tools to convert text to LaTex and then rather nice pdfs. For storage the most important thing is to put all documents and specs in one place. And if that one place is a version control system, then one can pull documentation for different points in time or different versions of a product. For specifications being able to do diffs on changes that are going on, to observe how a specification evolved over time, or to check who made changes is a huge time and fuck-up saver. As developers we all seem to have found value in putting code in version control systems. I don't make a strong distinction between documentation, specifications, and code. To me they are all product development artifacts that change over time. Dev artifacts that change over time defines what I want in source control.
Above I listed three documentation solutions that I have seen a various companies. Word in VSS worked the best and what I choose on my own personal projects is text files (Emacs org mode) or LaTex files kept in git. Infinitely more simple, less costly, and more efficient than anything I have used else where.
RSS Feed