Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I simply cannot imagine writing software without a spec. No matter how sketchy or high level it is, spec is important to explain to the clueless programmers on what are the functionalities of the program.

But the problem with spec is that it is somewhat a second class citizen in the whole software development cycle; when the development picks up the steam, it is neglected. But when dispute arises, the developers and testers and sales will scramble to find the spec to justify their grounds.

Either one or more scenarios will happen:

  1. The spec cannot be recovered, no one knows where is the spec
  2. Different versions of the spec emerge from different sources; it takes great difficulties to find out which version is the latest version, or whether there is a latest version available.
  3. The spec is incomplete, some parts of the documents it refers to are missing.

So spec management is important, and it's equally important that everyone has only One Single Source of Spec.

How do you manage your specs? I tried to get everyone to use Google Docs but everyone objected. Everyone is just too attached and enamored with Microsoft Word, which is-- in their opinion-- very easy to use, very easy to insert image, very easy to type equation and whatnot.

How to convince them that MS Word is just terrible for sharing?

share|improve this question

5 Answers 5

How to convince them that MS Word is just terrible for sharing?

Don't waste your time.

First. Spec should be in plain text (really) and under source code control. Use Markdown or RST or some other lightweight markup tool to produce a PDF or HTML page. Plain text.

Second. Take the various sources. Merge them. Write your own final document.

When they object, they have two choices.

  1. Use Google Docs (or the source code control tool) to edit your version.

  2. Continue to send you changes which you edit, filter and morph into the final document.

I prefer #2. Someone needs to "own" the spec. And a bunch of folks (wiki-style) leads to debates and change-wars and side-documents and off-line conversations and the like.

share|improve this answer

I don't think it is a "tool" issue but rather a "process" (or lack of process) issue.

You probably already have a process to release software (unit test, integration test, release letter, delivery, etc), you need to implement a documentation process as well.

  • Who is going to write the specs ? Who is going to update or maintain them ?
  • Who is going to review the specs ?
  • Who is going to approve the specs ? Architect, Project leader, QA?
  • How the specs are stored ?
  • Who is going to make sure that no obsolete versions are used ?
share|improve this answer

Some kind of control is definetly required.

It needs to be versioned, and signed off, and this process needs to be strict.

In too many places, sign off is neglected, and this leads to bun fights.

The location doesn't matter so long as it can be tracked

  • Sharepoint
  • a secure, backed up shared drive
  • I've seen some places use their code source control!!

But more importantantly you need buy in from all involved and 1 or 2 people who's responsiblity it is to manage both the document AND the sign off eg. the Project Manager.

share|improve this answer

MS Word is perfectly fine for creating a spec. We manage ours in SharePoint, which also handles the versioning. If you don't have SharePoint or another document management product handy, Google Docs is OK (you can now upload .doc/.docx files without converting them to Google Docs format). Or as others have suggested, you can even store them in your source code version control system (if the people creating the specs have access to that system).

share|improve this answer
 > How to convince them that MS Word is just terrible for sharing?

you cannot easily compare what-s the difference of two instances in a version-control-system.

I dont-t like word specs for that reason. But since it-s a political decision to use word-specs we have as first page "history informations" with these colums:

version-number(relates to product-verision), author, date, description

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.
{"cc_re__cc_re__cc_by_sa_3_0": ["        <li><a href=\"http://area51.stackexchange.com\" title=\"proposing new sites in the Stack Exchange network\">Area 51</a></li>\r\n                        <li><a href=\"http://careers.stackoverflow.com\">Stack Overflow Careers</a></li>\r\n                    \r\n                </ol>\r\n            </td>\r\n    </tr>\r\n</table>\r\n                </div>\r\n            </div>\r\n\r\n            <div id=\"copyright\">\r\n                site design / logo &#169; 2014 stack exchange inc; user contributions licensed under <a href=\"http://creativecommons.org/licenses/by-sa/3.0/\" rel=\"license\">cc by-sa 3.0</a> \r\n                with <a href=\"http://blog.stackoverflow.com/2009/06/attribution-required/\" rel=\"license\">attribution required</a>\r\n            </div>\r\n            <div id=\"svnrev\">\r\n                rev 2014.7.30.1736\r\n            </div>\r\n            \r\n        </div>\r\n    </div>\r\n    <noscript>\r\n        <div id=\"noscript-warning\">Programmers Stack Exchange works best with JavaScript enabled<img src=\"http://pixel.quantserve.com/pixel/p-c1rF4kxgLUzNc.gif\" alt=\"\" class=\"dno\"></div"], "copyright__copyright__copyright": ["of two instances in a version-control-system.\n\nI dont-t like word specs for that reason. But since it-s a political decision to use word-specs we have as first page \"history informations\" with these colums:\n\nversion-number(relates to product-verision), author, date, description\n\nshare|improve this answer\n\nYour Answer\n\n\u00a0\ndiscard\n\nBy posting your answer, you agree to the privacy policy and terms of service.\n\nNot the answer you're looking for? Browse other questions tagged or ask your own question."]}