7

Since no one prints anything any more, the concept of actual project documents (meaning, a monolithic piece of formatted text) seems like it could be improved on. Problems with documents are things like Word version incompatibilities, endless messing around with templates, the fact people hate reading them...

I'm wondering if there are alternatives, like websites that would help manage the content, imposing some structure, but allowing things like linking to individual bits. But I guess the site would have to be able to spit out a "document" for the times it's needed (filing, showing sponsors who ask, etc)

For example, instead of a "project plan document", I'm imagining a project planning site where you can work on just the resourcing with relevant people, then you work on scheduling with other relevant people, and work packages with other relevant people.

Instead of an SRS document, some site that lets you manage requirements, assigning priorities, phases etc...but that could ultimately generate an actual SRS document if you needed it.

Thoughts? The context here is small, agile teams but with occasional need to produce documents to demonstrate progress. We're certainly not big enough to warrant anything like Rational or whatever they use these days in big companies.

Jonas
  • 14,867
  • 9
  • 69
  • 102
Steve Bennett
  • 3,419
  • 4
  • 20
  • 24
  • "concept of actual project documents (meaning, a monolithic piece of formatted text)" Where did you find this? Can you provide a quote or a link? I've never seen such a claim, and I'd love to know where you got it from. [I'm not trying to dismiss your excellent question, I'm just asking for clarification. But you don't need to clarify if you don't want to.] – S.Lott Oct 03 '11 at 03:18
  • maybe "monolithic" is confusing - by "document", I really do just mean a Word document, a Google document, a web page. Like a project plan - typically a pretty long piece of text, with subheadings in order. But there is not, IMHO, much about the concept of the plan itself that dictates that Assumptions comes after Stakeholders. I'm questioning the imposed linearity. – Steve Bennett Oct 03 '11 at 07:23
  • 1
    Having worked on a system with a 1000+ page user requirement document, thats spawned dozens of other 1000 page design, test and other documents... I totally get the meaning of "...(meaning, a monolithic piece of formatted text)..." – mattnz Oct 03 '11 at 08:10
  • I was going to write a three word answer, "use a wiki", but then I saw that four of the existing answers already suggested that :) I'm sensing a pattern here... – eykanal Oct 03 '11 at 18:06
  • 1
    although I'm very much a wiki guy, most people I've worked with aren't. They're good at dumping stuff on the wiki, but not maintaining it. And they don't really do the rich interlinking that makes wikis shine. So a set of editable pages (like Google Docs) or a CMS seems to work better than an actual wiki. But I'm really hoping to find tools that are tailored to the software development process. A wiki can do anything. But it doesn't know the difference between requirements, design, bug fixes etc. Meanwhile I'm discovering some of the nice Agile features in Jira/GreenHopper - but... – Steve Bennett Oct 05 '11 at 07:14
  • ...they only give you small slices of information, it's not obvious how you would incorporate something bigger like an architecture diagram, a project plan, etc. – Steve Bennett Oct 05 '11 at 07:15
  • @SteveBennett: It's better to **update** your question than to add comments to it. – S.Lott Oct 05 '11 at 09:43

5 Answers5

3

I generally think that Word documents are generally a bad thing in software development. They're bulky, they're clumsy, they don't version well and searching them is painful.

In general, you should try to prefer document formats which version well. Binary heavy formats like Word, Excel, PNGs, have poor versioning support. That is, tracking changes is difficult and cumbersome.

Many documents are better stored in a Wiki. The limited formatting tends to force people to do simple formatting. Headers, lists, sections. Nothing complex, after all, the formatting can be bulk changed in one spot instead of updating some well hidden template file. Nothing is worse waste of people's time than dealing with pedantic document formatting.

Even images, some Wikis have support for Balsamiq mock-ups. Even if PNGs are necessary, a Wiki with PNGs is a far superior choice to Word files.

As for project planning, you should investigate tools which support Agile methods. I've used Jira successfully, but it's worth looking around to find a tool for your needs. Rigid design documents are generally a bad idea. They usually need a special tool like MS Project, and are difficult to update and share changes. As above, they also version poorly.

Using a Scrum tool you can define a list of relevant requirements and link from the Epic/User story item to the wiki which provides elaboration. So the wiki can version the meat of the ticket. Most scrum tools won't generate a Gantt chart but will do burn-down charts. A Gantt chart is proscriptive in that it defines reality, a burn-down chart is descriptive in that it can actually measure progress and make predictions about the future. Needless to say, the burn-down chart is much more useful.

Mark Robinson
  • 266
  • 1
  • 4
  • Thanks for some good ideas. On one project I'm managing (!) we're using Jira/GreenHopper, which the team is familiar with, but I'm not. It's an interesting experience. :) – Steve Bennett Oct 05 '11 at 07:18
  • Excellent advice, both in using **wikis** and tools supporting **Agile**. IMO, Word & Project are both hugely outdated tools and should be shelved by professional software companies. – Reinstate Monica - Goodbye SE Oct 14 '11 at 06:48
3

Since the target is small agile teams...

Favor formats which promote living documents. Printed documents aren't going away, the trick is to identify what needs to be printed and what doesn't so you spend your energy formalizing the right artifacts.

There are several tools that help with this. Two of the best are Wiki and SharePoint. MediaWiki can even export a PDF created from specific pages which can be used with stakeholders or for archiving snapshots. I've also had clients that preferred using hyperlinked reports that were exported directly from MediaWiki. All we had to do was create an index.html title page which provided an entry point into the report.

You might also take advantage of lightweight "oral history" practices. Some examples of these types of practices include...

In each of these examples, you could take a picture or make a video to upload to your Wiki or hold in SharePoint.

Michael
  • 2,102
  • 16
  • 22
  • 2
    +1 for sharepoint, it's not the greatest to dev for, but this is exactly what it's made for. At my company, we use both sharepoint and wikis. – Steven Evers Oct 03 '11 at 22:12
  • 1
    I really liked the thinking in the Architecture Haiku, particularly emphasising the use of trade-offs and dispensing with diagrams that don't add insight. – Steve Bennett Oct 05 '11 at 07:19
1

First off, people still print stuff constantly--it really depends on your particular corporate culture.

That said, try a wiki, so that people can collaborate, update, and link to their hearts' content while still having a history of their docs. Atlassian produces a fabulous on called Confluence which integrates really nicely with Jira, their bug/project tracking tool. Or else you could try one of the myriad free ones out there.

Matthew Flynn
  • 13,345
  • 2
  • 38
  • 57
1

I have seen wikis used like this, in place of documents. I think they were using Confluence, though there are many others. And yes, I think it could produce print-friendly documents on-the-fly.

Another thing to consider is what "documents" do you have besides Word documents? We have spreadsheets and Visio files which don't really have Wiki analogues (at least not as far as I know), so if you make heavy use of similar files, you'll have to attach them to the Wiki page and then reference them. Not a big deal, but something to keep in mind as it could change the way the document is read.

FrustratedWithFormsDesigner
  • 46,105
  • 7
  • 126
  • 176
  • I think there are starting to be analogues to both. There are obviously Google Spreadsheets, which work great. For diagrams, Gliffy allows collaborative editing of diagrams online. It seems incredibly useful, but expensive. – Steve Bennett Oct 05 '11 at 07:22
0

The problem is a database problem and should not be solved with word processes, spreadsheets or wikis.

Author IT is a nice document management tools that is designed to handle this problem. A problem is propritory format and therefore you need commit to it. However, if you are committed, it will do all you have asked and much more. I think it comes with a enterprise price tag, although they might offer something different.

mattnz
  • 21,315
  • 5
  • 54
  • 83