Posted on August 16, by Scott Alexander [Content note:
Models, Documents, and Source Code Let's start with understanding the relationships between models, documents, source code, and documentation, something depicted in Figure 1.
From AM's point of view a document is any artifact external to source code whose purpose is to convey information in a persistent manner.
This is different from the concept of a model, which is an abstraction that describes one or more aspects of a problem or a potential solution addressing a problem. Some models will become documents, or be included as a part of them, although many more will simply be discarded once they have fulfilled their purpose.
Some models will be used to drive the development of source code, although some models may simply be used to drive the development of other models.
Source code is a sequence of instructions, including the comments describing those instructions, for a computer system. Although source code is clearly an abstraction, albeit a detailed one, within the scope of AM it will not be considered a model because I want to distinguish between the two concepts.
Furthermore, for the sake of discussion the term documentation includes both documents and comments in source code. The relationship between models, documents, source code, and documentation.
Why Do People Document? Agile developers recognize that documentation is an intrinsic part of any systemthe creation and maintenance of which is a "necessary evil" to some and an enjoyable task for others, an aspect of software development that can be made agile when you choose to do so.
There are several valid reasons to create documentation: Your project stakeholders require it. The creation of documentation is fundamentally a business decision, you are investing the resources of your project stakeholders in the development of the documentation therefore they should have the final say on whether their money is to be spent that way, not a technical one.
If your project stakeholders request a document from you, perhaps at your suggestion, and understand the trade-offs involved more on this laterthen you must create the document.
It is important to note that eXtreme Programming XP is very explicit about documentation being a business decision. You should create documentation only when your project stakeholders ask you to?
Well, my experience is that this isn't preposterous. Your project stakeholders include a wide variety of people, including all of the clients of your system, and therefore they should have a reasonably good idea what they want. Maintenance developers, or someone representing them if they are not in place yet, will request system overview documentation.
Users and their management will likely request user documentation. Operations staff will request operations documentation. Yes, you will need to work closely with them to determine what they actually need, someone is going to have to decide to pay for the development and subsequent maintenance of the documentation, and you may even need to explain the implications of what is being requested, but this is doable.
To define a contract model. Contract models define how your system and an external one interacts with one another, some interactions are bi-directional whereas others are uni-directional, making the interaction s explicitly to everyone involved.
Contract models are often required when an external group controls an information resource that your system requires, such as a database, legacy application or information service.
The AM practice Formalize Contract Models states that a contract model is something that both parties should mutually agree to, document, and change over time if required. It is important to understand that the development of a contract model should still be verified by your project stakeholders-it is their money that you are spending, and if they choose to go at risk and not have the contract model in place then that is their choice.
To support communication with an external group. It isn't always possible to co-locate a development team and it isn't always possible to have project stakeholders or at least the ones you need at the time available at all times.
When you need to work with an external group of people you need to find ways to communicate with them, and shared documentation is often part of the solution in combination with occasional face-to-face discussions, teleconferencing, email, and collaborative tools. It is a mistake to use documentation as your primary means of communication because it's far too easy to misunderstand something that has been written, but it is a good supporting mechanism.
A good way to think of documentation in this situation is that it is your option of last resort. Note that this in effect is an extension of the practice Model to Communicate into the realm of documentation. To support organizational memory.
An important implication is that we not only need to develop software, but we also need to develop the supporting documentation required to use, operate, support, and maintain the software over time.Change Management - Change Management Introduction In the world of large organizations there is a strong temptation to streamline operations by having blanket systems and procedures in place.
Figure barnweddingvt.com relationship between models, documents, source code, and documentation. 3. Why Do People Document?.
Agile developers recognize that documentation is an intrinsic part of any system, the creation and maintenance of which is a "necessary evil" to some and an enjoyable task for others, an aspect of software development that can be made agile when you choose to do so.
In the political world, we experience the wave’s peak moments through events like elections or policy wins, but we don’t always recognize the undercurrents and conditions that lead us there.
2 Strategically Communicating Organisational Change Abstract The purpose of this essay is to help organisations more effectively implement change.
Friendships are unique relationships because unlike family relationships, we choose to enter into them. And unlike other voluntary bonds, like marriages and romantic relationships, they lack a. When we change how we communicate, we change who we are Essay Sample.
When we change how we communicate, we change who we are. Communication can be used to alter a persona, depending on how they carry themselves by the language they use.