When designing systems or preparing presenations its important to understand your documents.

Vague documents occur when trying to put too much information into a single document that does not directly aid the purpose of the document. That information may confuse the reader as the document drifts from one topic to another. Such information should be put in a different document. When presenting some point of view and producing some presentation, its important to back your results with strong sources.

Its better to build up many sets of correct and consise documents that are easy to update when information changes or becomes available. Furthermore, different types of documents may depend on (and source) information from numerous documents without confusing the scope and purpose of the document.

Consider what happens when putting together an technical integration manual. The manual should source information from various internal technical notes and apis. Any new information should be updated and corrected in the technical notes, not the technical manual. It is typical to have technical writer compose the manual from specifications and notes. The techical writer is not typically the authority to create the source material. When the manual contains original material, the documentation style is either (a) the manual is the specification, or (b) the manual is dependant on source material, source material should be updated or source material is unique to the manual, or (c) there is no source material.

A problem with many source documents is being able to find the documents and having someone review changes to the document. Google Desktop Search is an example of an effective way to find what you're looking for while MS Sharepoint Portal Server provides both reasonable search functionallity and document process control (i forget the correct terminology). Unfortunately MS SPS is cost prohibitive for smaller businesses.

Either way, documentation is costly to create so its important to be effective in its creation and use.

---

Reliable + Cheap = Lots of preparation and documentation (not fast)
Cheap + Fast = Little preparation and documentation (lets go live)
Fast + Reliable = Someone else did the documentation and are charging for it.

---

The scope of this is again possibly too large and vague in itself. Am i trying to jot down my thoughts... or am I trying to put together a javaworld.com article.

Pick Two

(a) Reliable
(b) Cheap
(c) Fast

An XML namespace is not a URL, its a URI. If it looks like a URL (http://mycompany.com/food/thought), it should resolve to an RDDL instead of 404 not found. If it is not a URL it should be a URN (urn:mycompany.com:food/thought).

O'Reily on RDDL has a good document to get you into the headspace.

www.rddl.org has the RDDL specification.

Since a URL is tied to a companies web deployment, i'd structure the URIs such that they dont collide with web content. The webserver should map the final part of the namespace to an RDDL file.

http://<site>/uri/<unique-part>/<version>

namespace URL: http://frogs.com/uri/food/flying-things/1.0

site: frogs.com
unique-part: food/flying-things
version: 1.0



One thing... security. I dont want to let the rest of the world know my internal protocols and schemas. This could be enforced by a secure site (internal.site.com) or protected areas on the site.

I keep on reading about SOA (Service Oriented Architecture) and how its some sort of silver bullet. I then read as many critics about how (1) SOA is actually just stateless RPC (2) over Web Services; (3) its no silver bullet - cannot do X, Y, Z; (4) it already exists in many companies using different protocols; etc, etc, etc.

I fear that many miss the point and get confused between the architects point of view and the sales-man's/advocate point of view.

The sales man wants to sell an idea because he's either wants to make a profit by providing a consulting service; or is some sort of idealistic fanatic.

The architect/researcher's point of view is that the SOA concept has been identified as a real and worthwhile enterprise pattern. The discussion and research around SOA is focused on increasing the total understanding around how to apply the concept to the enterprise, what the implications and limitations are and how to cleanly implement the pattern across a large enterprise. Two points to consider - (a) It is better to have a well understood enterprise architecture whose implications and limitations are well researched than having an architecture arise without control and without understanding its limitations, (b) SOA is mostly applicable to a subset of problems.

Now sometimes ...

the advocate/fanatics miss point (b) - so they advocate SOA everywhere.
the critics dont understand (b) - so they dont see the value of the pattern.
the architects dont understand (b) - so they try to apply the pattern to every problem.

...

My house got hit by lightening last night... Happiness and burnt wires. For some reason it was only the circuit with the house lights... and the house alarm. (I have a house alarm?)

It became apparent that there was a house alarm when it started going off at 4am in the morning. This poses 3 questions... Where is it, Why is it going off, and How do I turn it off. After a short amount of time it became apparent that the pin-code was not known so it was not possible to electronically disable the sirens/speakers. These were physically disabled. Next up... the buzzers in each circuit board hidden in cupboards and other wonderful places. Removing those circuit boards solved that problem.

Great stuff. 6 hours sleep and a headache. Now to hope that the next door neighbour doesnt try to evict us.

A summary of an enterprise SOA architecture - The Rings of the Enterprise [link]

Ring Zero: WS/RMI/.NET Remoting, Java/C#, business logic + processes, databases, no security
Ring One: Messaging middleware, business system, application security, secure sockets
Ring Two: B2B collaboration, security is a big issue, firewalls, encrypted comms
Ring Three: The world, unsafe


Since Ring Zero has no security, I would expect a business process to be implemented to ensure that staff are unable to interfere with the live system / ring zero. In the simpest of applications, this would imply that a developer doesnot imbed some sort of backdoor or "feature". The security process would be code review. In a larger enterprise system it would be complete network isolation of ring zero allowing only ring zero and ring one to communicate. A deployment process that ensures only certain individuals have access to the live system and a QA review and testing process independant of the developers.

When using IEEE Software Engineering Process, you will find yourself overwhelmed with how many different templates and processes are defined. Realise that a single person is not supposed to create all the different IEEE documents and you will not typically find someone who is an expert in all the related fields. The IEEE is not suited for companies where architect == deverloper == tester == etc.

The roles of architect, developer, tester, etc will typically author their various documents and when those roles are correctly performed, an individual will typically never have to compose all of those documents. The author of the various documents should try to stick as close as possible to what is needed by document (as defined by the particular IEEE standard). When all documents are not authored, you will find a need to place some 'important' information inside a document because it has no appropropriate place.

Stick to the process and put that information in the correct document, as opposed to forcing it into some inappropriate document - otherwise your documents will become vague. The documentation may also require particular diagrams as an aid in the discussion. Dont try to put additional diagrams that will be (or are) duplicated by another part of the documentation process.

The whole IEEE Software Engineering Process might seem heavy until you stop duplicating information that has been documented or will be documented. In addition, the correct stakeholders should drive the correct parts of the process so that roles do not overlap.

The problem with investing great amounts of time in UML, before you need to discuss a particular topic, is that there are many different views of the same system. Unless you're talking to another coder, a class diagram will not aid in discussing business logic. There are typically quite a few representations of the same system and based upon your discussion only one of those is of any use. Composing these diagrams can be highly time consuming for small projects at the risk of not completing the small project at all. For larger projects its probably impossible to diagram every aspect unless you employ the use of design recovery companies.

While excessive time to compose a correct and complete model of design does not constitute a failure of UML (dont ask me to develop and formalise such a large diagram), I do think that UML is necessary. If you cannot communicate correctly, on at least a small scale, then you're at a disadvantage. There are many diagramming methodologies of which a professional should understand and use at least one modelling system correctly. That is: the ability to use the correct diagram to quickly sketch the interactions being discussed instead of using the incorrect diagram and forcing information into the diagram.

A UML Tutorial [Link]