File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
The moose likes Agile and Other Processes and the fly likes what kind of document does an architect typically has to create ? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "what kind of document does an architect typically has to create ?" Watch "what kind of document does an architect typically has to create ?" New topic

what kind of document does an architect typically has to create ?

Fei Teng

Joined: Feb 07, 2006
Posts: 4
Often read the articles that java architect delivers design documents for developers. In software industry, what typical document a java architect should deliver to developers and client (users) respectively ?
Lasse Koskela

Joined: Jan 23, 2002
Posts: 11962
The title "software architect" has as many meanings as there are companies with "software architects" on their staff.

Personally, I consider an architect to be someone who doesn't just "create documents" but who creates working software in addition to having an integral role in shaping the said software product's design and architecture.

In other words, I don't give much value to architects who can't code. Note that I'm saying "can't" and not "don't", because there are software architects I know who don't write any code but I know they could. It's the skill of knowing the consequences of one's decisions and knowing what you're doing that separates the "real" architects from those who'd just like to continue drawing their pretty diagrams and never have to actually do something useful.

I'm pretty sure I didn't answer your question, but I believe sharing my thoughts on the architect role might have some value...

Author of Test Driven (2007) and Effective Unit Testing (2013) [Blog] [HowToAskQuestionsOnJavaRanch]
Scott Ambler
Ranch Hand

Joined: Dec 12, 2003
Posts: 608
Architects don't have to create any documents, and as Lasse indicated good ones certainly don't focus on documentation.

At Agile Architectural Modeling, Enterprise Modeling Anti-Patterns, and Agile Enterprise Architecture I describe some effective strategies (and in the case of the anti-patterns some not so effective ones) which you might finds of interest.

In short, if you focus on documentation you shouldn't be surprised if the developers ignore your advice, no matter how good it is.

- Scott

<a href="" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Kishore Dandu
Ranch Hand

Joined: Jul 10, 2001
Posts: 1934
I concur with Lasse. At the same time, depending on the environment you are working on; you might be the primary responsible person who is mandated to provide different design artifacts for ongoing projects.

Irrespective of what different agile gurus(here and elsewhere) are touting stuff, it all depends on the environment you are working as a architect.

SCJP, blog
Reid M. Pinchback
Ranch Hand

Joined: Jan 25, 2002
Posts: 775
An architect is responsible for coming up with an approach to the project that is going to work. Documents make sense to the degree that:

(a) they help the architect really create the starting point for a workable solution, and

(b) give the architect something that communicates to others the intended direction.

I saw one case where the "architecture documentation" was literally hundreds of pages along and thus rendered nearly useless from a development standpoint, although I'll acknowledge that at the time there were non-development business reasons behind the creation of that monstrosity (in other words, some of "b" above plus sales pitch, durned little of "a"). I'd focus less on "what kinds of documents should an architect create?" and more on "who are the players in this project and what do I need to communicate to them?". If the only players are developers and your manager, then "documentation" may just be the whiteboard in your office. If you are trying to impress a potential business client who hasn't yet committed to the project, the communication/documentation issues could be completely different.
[ February 11, 2006: Message edited by: Reid M. Pinchback ]

Reid - SCJP2 (April 2002)
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I'm going to turn this a bit from "What would the best agile team do" to "What documents (buzzwords?) should you know to go for an architect posting in HotJobs".

I borrowed this list of uses for architecture documents from Carnegie Mellon. The original article is linked from there and has more info on such documents. This gives you a good idea of what lots of companies are thinking.

The definition of the architect role varies greatly between companies, consultants and teams. I think at my company it is probably the sum of all other definitions and we're on the way to having architects outnumber developers. We produce tons of documents ranging from physical hardware allocation with IP addresses and ports to high level software architecture to detailed design of selected parts of an application. They go to deployment folks, production support, enterprise architects for review and approval, partner systems for interface development and so on.

Let me know if any of that was on target for the original question.

A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
I agree. Here's the link:
subject: what kind of document does an architect typically has to create ?
It's not a secret anymore!