Rules for sound documentation

Documentation should be written from the point of view of the reader, not the writer.
Documentation should be organized for ease of reference, not just ease of reading.

Avoid repetition. Each kind of information should be recorded in exactly one place. This makes documentation easier to use and much easier to change as it evolves. It also avoids confusion, because information that is repeated is often repeated in a slightly different form, and now the reader must wonder: Was the difference intentional? If so, what is the meaning of the difference? What information was the author trying to convey to me that I am not picking up?

Avoid unintentional ambiguity
One of the greatest sources of ambiguity in architecture documentation are those ubiquitous box-and-line diagrams that people often draw on whiteboards or backs of napkins. While not a bad starting point, these diagrams are certainly not architectures. For one thing, the behavior of the components is not defined, and this (as we shall see) is a crucial part of the architecture. But beyond that, most of these diagrams suffer from ambiguity with respect to the component and connector types. Are the boxes supposed to be modules, objects, classes, processes, functions, procedures, processors, or something else? Do the arrows mean submodule, inheritance, synchronization, exclusion, calls, uses, data flow, processor migration, or something else?

Use a standard organization. Each document should conform to a standard, planned organization scheme, and this scheme should be made known to the reader. A standard organization offers many benefits. It helps the reader navigate the document and find specific information quickly (and so this is also related to the write-for-the-reader rule). But it also helps the writer of the document. It helps plan and organize the contents,

Record rationale. If you are documenting the results of decisions, record the decisions you eschewed and say why. Next year (or next month) when those decisions come under scrutiny or pressure to change, you will find yourself revisiting the same arguments and wondering why you didn’t take some other path. Recording rationale will save you enormous time in the long run, although it requires discipline to record in the heat of the moment.

Keep it current. Documentation that is incomplete, out of date, does not reflect truth, and does not obey its own rules for form and internal consistency will not be used. Documentation that is kept current and accurate will be used. The reason is that, backed up by high-quality documentation, questions about the software can be most easily and most efficiently answered by referring the questioner to the appropriate document.

Review documentation for fitness of purpose.

(Source: I don’t recollect where I got this from, as and when I find out I wll update this)

Principles of Objectivism

The basic principles of Objectivism can be summarized as follows:
 
Metaphysics
"Reality, the external world, exists independent of man's consciousness, independent of any observer's knowledge, beliefs, feelings, desires or fears. This means that A is A, that facts are facts, that things are what they are—and that the task of man's consciousness is to perceive reality, not to create or invent it." Thus Objectivism rejects any belief in the supernatural—and any claim that individuals or groups create their own reality.

 
Epistemology
"Man's reason is fully competent to know the facts of reality. Reason, the conceptual faculty, is the faculty that identifies and integrates the material provided by man's senses. Reason is man's only means of acquiring knowledge." Thus Objectivism rejects mysticism (any acceptance of faith or feeling as a means of knowledge), and it rejects skepticism (the claim that certainty or knowledge is impossible).

 
Human Nature
Man is a rational being. Reason, as man's only means of knowledge, is his basic means of survival. But the exercise of reason depends on each individual's choice. "Man is a being of volitional consciousness." "That which you call your soul or spirit is your consciousness, and that which you call 'free will' is your mind's freedom to think or not, the only will you have, your only freedom. This is the choice that controls all the choices you make and determines your life and character." Thus Objectivism rejects any form of determinism, the belief that man is a victim of forces beyond his control (such as God, fate, upbringing, genes, or economic conditions).

 
Ethics
"Reason is man's only proper judge of values and his only proper guide to action. The proper standard of ethics is: man's survival qua man—i.e., that which is required by man's nature for his survival as a rational being (not his momentary physical survival as a mindless brute). Rationality is man's basic virtue, and his three fundamental values are: reason, purpose, self-esteem. Man—every man—is an end in himself, not a means to the ends of others; he must live for his own sake, neither sacrificing himself to others nor sacrificing others to himself; he must work for his rational self-interest, with the achievement of his own happiness as the highest moral purpose of his life." Thus Objectivism rejects any form of altruism—the claim that morality consists in living for others or for society.

 
Politics
"The basic social principle of the Objectivist ethics is that no man has the right to seek values from others by means of physical force—i.e., no man or group has the right to initiate the use of physical force against others. Men have the right to use force only in self-defense and only against those who initiate its use. Men must deal with one another as traders, giving value for value, by free, mutual consent to mutual benefit. The only social system that bars physical force from human relationships is laissez-faire capitalism. Capitalism is a system based on the recognition of individual rights, including property rights, in which the only function of the government is to protect individual rights, i.e., to protect men from those who initiate the use of physical force." Thus Objectivism rejects any form of collectivism, such as fascism or socialism. It also rejects the current "mixed economy" notion that the government should regulate the economy and redistribute wealth.

 
Esthetics
"Art is a selective re-creation of reality according to an artist's metaphysical value-judgments." The purpose of art is to concretize the artist's fundamental view of existence. Ayn Rand described her own approach to art as "Romantic Realism": "I am a Romantic in the sense that I present men as they ought to be. I am Realistic in the sense that I place them here and now and on this earth." The goal of Ayn Rand's novels is not didactic but artistic: the projection of an ideal man: "My purpose, first cause and prime mover is the portrayal of Howard Roark or John Galt or Hank Rearden or Francisco d'Anconia as an end in himself—not as a means to any further end."

Excerpts from www.aynrand.org

Fundamentals of IT consulting

Excerpts from fundamentals of IT Consulting from www.techrepublic.com

There are five basic concepts that can serve as a foundation for the IT advisory process:

• Focus on the relationship: Identifying who the client is, and understanding the motivations, culture, history, fears, and goals of both the human being and the organization he or she represents, is one of the most difficult tasks in consulting. Your success in this task has much more bearing on the success or failure of your engagements than the technical discipline involved.


• Clearly define your role: Setting the expectation with the client regarding exactly what you are there to accomplish, what tasks you are making a commitment to perform, what tasks you expect the client to perform, and where the boundaries of the relationship lie, is a key success factor for consultants.


• Visualize success: It is the consultant’s central role to help the client draw a mental picture of the desired result of the engagement. Failure to do so results in the dreaded scope creep, in which the engagement never concludes because the expectations keep changing. Visualizing a successful result creates a common goal that all participants can agree upon and strive for together. Like the championship ring for a sports team, it is an unambiguous and motivational endpoint that clarifies the effort and helps clear away extraneous issues and barriers.


• You advise; they decide: One of the most difficult tasks for consultants is to cast aside emotional attachment to their own advice. Many technicians fall in love with a particular solution or technology, and then lose interest in, or respect for, the client if he decides to take another approach. We must always remember that the client understands the complexities of his own environment, and that he lives with the result of his decision, while we move on to the next assignment.


• Be oriented toward results: Consulting is more than advising, it is assisting clients to reach a goal. While some advisory relationships are strictly informational, most clients want us to not only recommend solutions, they want us to help implement them. Politics is often described as “the art of the possible,” a good definition for results-oriented consulting as well. By considering implementation issues throughout the engagement, such as corporate culture, readiness to change, training requirements, and corporate communications channels, we keep our eye on the realm of possibility, avoid getting sidetracked into the theoretical, and prepare the client for the real-world issues of implementation and system operation.