Software Specification Help
July 17, 2007 6:56 AM Subscribe
Help! I need some good suggestions regarding tools and methods for creating and maintaining a large set of interrelated software specifications and documentation.
On the heels of my last question regarding Software Specifications:
Have any of you worked with Wiki or something similar for managing software specs (like at OpenOffice.org)? I'm working on an ERP project in which I've generated hundreds of pages of technical specifications in a multitude of Microsoft Word documents. Other people involved with the project have generated more hundreds of pages of specs - functional, technical and other documentation (user docs, wireframe mock-ups, etc.).
As my project Documentation folder fills up with more and more new documents, I'm starting to lose the overview, and I'm noticing that it's sometimes hard to figure out where certain pieces of info should go. I'd like to have a system that's easier to navigate, and that is crosslinked (automatically, if at all possible) like a wiki, so I can define a term or feature in one place and link to it from the other documents that need to refer to it. It would also be nice to allow other users to comment and/or edit the documents (as long as edits were tracked).
This project is getting bigger and bigger. More developers are working on it, and the complexity is increasing daily. Any tips for a better way to handle this than 50 Word docs, each with 15-80 pages?
On the heels of my last question regarding Software Specifications:
Have any of you worked with Wiki or something similar for managing software specs (like at OpenOffice.org)? I'm working on an ERP project in which I've generated hundreds of pages of technical specifications in a multitude of Microsoft Word documents. Other people involved with the project have generated more hundreds of pages of specs - functional, technical and other documentation (user docs, wireframe mock-ups, etc.).
As my project Documentation folder fills up with more and more new documents, I'm starting to lose the overview, and I'm noticing that it's sometimes hard to figure out where certain pieces of info should go. I'd like to have a system that's easier to navigate, and that is crosslinked (automatically, if at all possible) like a wiki, so I can define a term or feature in one place and link to it from the other documents that need to refer to it. It would also be nice to allow other users to comment and/or edit the documents (as long as edits were tracked).
This project is getting bigger and bigger. More developers are working on it, and the complexity is increasing daily. Any tips for a better way to handle this than 50 Word docs, each with 15-80 pages?
What's 11-dev? Link? Googling gave me nothing useful. Maybe I'm dumb though.
posted by zackola at 9:26 AM on July 17, 2007
posted by zackola at 9:26 AM on July 17, 2007
Response by poster: zackola: 11-dev is the latest development version of the Trac software. Do a find for "0.11dev" on the trac download page.
posted by syzygy at 9:35 AM on July 17, 2007
posted by syzygy at 9:35 AM on July 17, 2007
Response by poster: Crap "herf" != "href". Trac Download page.
posted by syzygy at 9:36 AM on July 17, 2007
posted by syzygy at 9:36 AM on July 17, 2007
That page lists 0.10.4 as the latest available release for download. Am I missing something about where 11dev is?
posted by spicynuts at 11:14 AM on July 17, 2007
posted by spicynuts at 11:14 AM on July 17, 2007
I'll second trac as a good specification/documentation/implementation development mixture. It also has a decent plugin architecture and there are many plugins available, depending on what your specific requirements are.
posted by dkg at 7:18 PM on July 17, 2007
posted by dkg at 7:18 PM on July 17, 2007
Response by poster: OK, trac sounds interesting. I spoke with my boss about it shortly yesterday afternoon. Apparently, other units in our company are already using it.
It's good to know about the plugin architecture (although trac-hacks.org is currently down for me).
The main thing I'm looking for is automatic crosslinking, or even better, a tool that offers different views on the same data - something like the following example:
I need a "database schema" view that shows me all tables in one document.
I need a "feature x" view that shows me all info on feature x, including the db tables that it it touches (taking that db info from the same place as the "database schema" view takes its info), plus links to other features that are somehow dependent on or related to feature x.
I'd prefer something like the above over simple crosslinking. Wishful thinking?
Also, another question. Word is pretty nice when it comes to editing the documents and tracking edits (along with formatting, styles, etc.). Is moving to editing in a wiki-style going to be a real pain?
posted by syzygy at 2:36 AM on July 18, 2007
It's good to know about the plugin architecture (although trac-hacks.org is currently down for me).
The main thing I'm looking for is automatic crosslinking, or even better, a tool that offers different views on the same data - something like the following example:
I need a "database schema" view that shows me all tables in one document.
I need a "feature x" view that shows me all info on feature x, including the db tables that it it touches (taking that db info from the same place as the "database schema" view takes its info), plus links to other features that are somehow dependent on or related to feature x.
I'd prefer something like the above over simple crosslinking. Wishful thinking?
Also, another question. Word is pretty nice when it comes to editing the documents and tracking edits (along with formatting, styles, etc.). Is moving to editing in a wiki-style going to be a real pain?
posted by syzygy at 2:36 AM on July 18, 2007
Wishful thinking, but if any of you know Python you could write a plugin.
I currently, in Trac, use syntax equivalent to html's pre tag to lay out databases in YAML. (This works especailly well because we're symfony developers and the database tables can just get pasted into our schema.yml.) So while you can't automatically create crosslinks, there's a plugin for 'what links here' and you can quickly type names that are CamelCasedWords and they'll automagically become links ... funny how we started using all CamelCasedPHPObjectNames, innit?
And sorry about the confusion about 0.11dev. It's main features are better security, integration of one or two best-of-breed plugins, and a new workflow system for tickets as well as a ton of refactoring, replacement of the templating engine, and lots and lots of hacking.
The wiki will give you the ability to see a history of edits, and to fall back to specific versions or diff between specific versions. It's very nice.
posted by SpecialK at 5:18 AM on July 18, 2007
I currently, in Trac, use syntax equivalent to html's pre tag to lay out databases in YAML. (This works especailly well because we're symfony developers and the database tables can just get pasted into our schema.yml.) So while you can't automatically create crosslinks, there's a plugin for 'what links here' and you can quickly type names that are CamelCasedWords and they'll automagically become links ... funny how we started using all CamelCasedPHPObjectNames, innit?
And sorry about the confusion about 0.11dev. It's main features are better security, integration of one or two best-of-breed plugins, and a new workflow system for tickets as well as a ton of refactoring, replacement of the templating engine, and lots and lots of hacking.
The wiki will give you the ability to see a history of edits, and to fall back to specific versions or diff between specific versions. It's very nice.
posted by SpecialK at 5:18 AM on July 18, 2007
Response by poster: SpecialK - that sounds interesting, at least, but not 100% what I'd like to have. I'll take a close look at Trac to make sure, though.
Pperhaps someone knows of a content-management system that meets my requirements? I'm looking at Joomla and Drupal right now. Or maybe Wordpress? Something that allows me to create document "sections" that can be pulled into multiple complete documents.
posted by syzygy at 8:40 AM on July 18, 2007
Pperhaps someone knows of a content-management system that meets my requirements? I'm looking at Joomla and Drupal right now. Or maybe Wordpress? Something that allows me to create document "sections" that can be pulled into multiple complete documents.
posted by syzygy at 8:40 AM on July 18, 2007
This thread is closed to new comments.
The wiki is great because you can reference tasks/tickets and releases in the wiki using shortcuts... i.e. typing r245 in the wiki will reference revision 245 in SVN; in the same vein, typing #654 will reference ticket number 654. That way you can link the actual tasks to the area in the specification where they're discussed and vice versa, and if you are documenting a particular snippet of code you can link to it's location in the source code repository by revision and file name.
posted by SpecialK at 7:21 AM on July 17, 2007