Talk:Technical writing/Specification

Course exercises page

Exercise will be done "live".

Each student makes userID. We created lesson wiki page. Each group creates a page linked to this (using naming convention). One user from each group takes turn as writer (shift places). First writer copy/pastes the example wikitext into their page.

This approach requires at least some instruction on wiki markup, especially how to write tables...TWFred 13:43, 24 September 2007 (UTC)

Exercise 1

Writing requirements

1. Compose 5-10 requirements for a calculator.
2. Compose different types of requirements (functional, non-functional).

You can interview your "customer" to find out their needs and requirements. You can use the template below to record your requirements.

Note Your trainer will provide you instructions how to use wiki.

Exercise 2

Evaluate requirements

1. Evaluate requirements.
2. Make necessary corrections.
3. Provide comments.

Requirements Template

List the functional requirements for each functional requirements group.

Functional Requirements Group 1 (e.g. User Interface)

Req. ID	Definition	Description	Comments
UI-010
UI-020
UI-030
UI-040

Functional Requirements Group 2 (e.g. Math Funcitons)

Req. ID	Definition	Description	Comments
MF-010
MF-020
MF-030
MF-040

Non-functional Requirements

List non-functional requirements (e.g. Performance, Design Constrains, Safety, etc.)

Group 1

Req. ID	Definition	Description	Comments
R-010
R-020
R-030
R-040

Where do the use cases fit in?

---

I usually do requirements gathering, analysis and app design. I have a problem with this article. I was surprised and hurt not to find the term "use case" at least once inside it.

Failure rate of projects in the team I'm working in is low (less than 10%) - which means that 90% of all projects are delivered on time (at most a week late for projects running over half a year or so), withing budget (well, at most 10% overrun sometimes happens, but seldomly), and feature-complete (based on the specification). Not one project we started lately was canceled or suffered from bad user acceptance. Judging by what the chaos reports say, we're pretty good at what we're doing, I think.

But our specification process does in no way resemble what is preached here! In fact, earlier on, when we did something which to some extent looked like the examples in this article, we had a significantly higher failure rate (approaching 50%). As far as I can tell, this was simply because the specification process as you explain it is hard to structure for the person doing the requirements gathering and analysis (and writing it all down), hard to validate for QA, and even harder for the programmer to use during implementation or the tester to use during testing. Therefore, as we found out the hard way, the creation of specs is not simply a process to get all the customer requirements together, or to specify what and how has to be implemented, but an important bit more: to do this in a way which generates documents which are usable by testers and programmers.

Another issue with specs is that they need to be maintained, just like any other artifact which is created during a SW development project. Otherwise they are useless. Most programmers know the difference between maintainable and unmaintainable code. The difference between maintainable and unmaintainable documentation is similar. Since there are no "design best practices", "documentation design patterns" or the like for specs in this article, I find it unlikely that this article trains technical writers for properly writing specs.

Programmers often use frameworks, which are more or less general, or more or less domain-specific, for quickly developing good apps. I think that unless an article on specs in wikiversity provides some clues on developing such a framework. Templates won't cut it, as far as I can tell, since they focus on form rather than content. It's like substituting code formatting rules for a framework when you write code.

Some things that make good and maintainable code are having classes contain only related methods and members. IMO, this is is essentially what makes documentation maintainable: writing about one thing only in one part of a document, keeping all related issues together, and maintaining a standardized, easy to follow structure of references. How do you build documentation which matches these simple criteria out of nothing?

So it may be useful to briefly explain what we do to get to a specification which is useful for the ppl writing the software and understandable by the customer's ppl - which in most cases are not at all computer savvy.

It may also be important to note that what we do typically is small to medium business automation apps - workflow apps, document management, directories, data aggregation, all sorts of apps for managing various information. This is probably influencing our analysis, design and documentation process. But even if I think of a completely different app, for instance a brand new database engine, I think the requirements gathering and analysis process would be usable. Probably only the design process would need to be different. But I think the resulting design documentation would have the same structure.

We do not start out blank. The detailed specification process starts after the contract was signed, and after a price tag was placed on the project. However, the process which leads to the signing of the contract is more or less the same as the one leading to the detailed specs, only rougher, with less detail. However, it almost never happens that we make significant errors in the initial estimation. We try to agree with the customer on content in advance, and the following specification process just puts the agreed content into a very detailed written form - and the specification of the details is what takes most of the time and what makes the difference between a successful and a failed project, as far as I can tell.

We do one or more workshops, as needed. We try to plan the workshops over the phone, by email, IM, and by any other means so that all important stakeholders are present, and try to discuss all important aspects in advance also. Ideally, and not very seldom, one carefully planned workshop is enough, accompanied by intensive communication before and after the workshop, but this is probably due to our projects being rather small (at most a few man-years). During the workshop(s) we try to model the business process to be. Since all involved ppl are there, the resulting modes should be pretty much usable. Afterwards, we write a document containing a glossary, mostly use cases defined using the terms in the glossary, and, if necessary (almost always necessary), non-functional requirements (such as scalability, reaction times, graphical standards, and the like - just about anything that cannot be formulated as a use case, and also all awkward, non-negotiable customer requirements). In case of more complicated use cases, these are augmented with workflow diagrams, or the like. Main criteria for this document however is that it stays understandable for the customer and the end users, on one hand, and that it doesn't contain design - other than non-functional requirements of conformance to coding, layout, architectural or other standards. The requirement that the use case be readable by end-users effectively forbids formulating use cases "by the book", i.e. using pre- and post-conditions, invariants and the like. Of course, these should be there, just not formulated as sutch - the mere occurence of the term "invariant" might scare away a reader who is a graphical designer, and who just ordered an app to allow him to make files available for download for his customers.

This document goes through several review/correction cycles, until the customer is happy with it. This is the most important document in the entire development process, for us. Get this even slightly wrong, and the project is bound to fail.

This is what we call the functional specification. It is easily read, because each use case describes a simple process, and thus easy to validate by the customer. It doesn't bind you to a specific technology or design, since it is not allowed to contain references to such things, unless they are part of the non-functional requirements. It is by its nature easy to understand, since all use cases are based on terms in the glossary, which includes states, actors, business concepts, in short, most terms which are even slightly likely to be assigned different meanings by ppl with different backgrounds. But most important, the software designer has it easy when he uses this document to do the design, and QA has also an easy time creating test cases based on the use cases. It is easy for the designer to elicit the data structure and operations based on the use cases. Testers just add input and expected output to use cases, and there you have the test cases.

Further on, the whole process is simple. The use cases allow the more or less straighforward extraction of a sound data structure, which is a solid foundation for a sound architecture. Adding functionality based on the data structure, especially when having the individual use cases properly described, is easy. Having the whole design upfront allows for some refactorings which optimize the design upfront, before the code is written.

The design is usually modeled using class diagrams, ER diagrams, less often state or activity diagrams. However, essentially, when you have the use csaes, you can pretty much document all your design using just UML diagrams with comments which reference the use cases. It is really easy afterwards for the coders to work based on the functional specification and the code directly generated from the UML class diagrams - as far as I can tell, letting code generation take into account other UML diagrams as well sometimes damages your code, but this may also be a matter of what tool you use.

Hence, my question: if not this way, where do use cases fit into the specification the way you try to preach it? How can you assure that the functional specs written without use cases match usability criteria for the software architect, the tester and the coder?

86.106.39.91 14:11, 6 January 2008 (UTC)

Use Cases are Vital

Thank you, anonymous contributor of the previous comment.

You describe an ideal development process. It must be great to be part of a team like that. My hat is off to you.

Sorry if I'm "preaching" anywhere here. I'll do my best to copy/paste/edit your words and add more about use cases to this technical writing wikiversity. But I need your help! Click that Edit tab, my friend and colleague!

You are one hundred percent correct there is not enough about use cases. I just don't know where to start. Should it be a separate wikiversity altogether (it's certainly worthy) or should it be integrated into the entire technical writing course?

In some ways, I've just skirted the issue by focusing more on how to actually word things.

I also freely admit that with the exception of the triangular diagram and the simple sentence diagram, I don't think anything here is original. I'm mostly rewording what is conventional wisdom. I welcome innovators like yourself to improve what we're doing here. I'm one of the primary authors, but it's nothing I "own" at all. Quite the opposite, it is what we want to share that matters.

Please share more. You write beautifully.

Please send me a wikiversity email. I want to discuss this with you.

Thanks again, TWFred 07:03, 17 January 2008 (UTC)

link removal

Hi, this link was removed, because someone reported a problem due to the Spam protection filter, see colloquium, ----Erkan Yilmaz uses the Wikiversity:Chat (try) 20:54, 25 March 2008 (UTC)

The IP address is for google, so 209.85.135.104 can be replaced by www.google.com in the link to get it working. Just cut and paste A Template to where you want the link in the page. --mikeu ^talk 21:06, 25 March 2008 (UTC)

Replaced, ----Erkan Yilmaz uses the Wikiversity:Chat (try) 01:27, 26 March 2008 (UTC)

IEEE 830

ever heared of IEEE 830?

"Characteristics of good requirements specifications"

How can a decent course do without it? (the issues are just partially addressed here)