Labog, Althene Faustine T.

BSIT 4-1 Part 2: Related Studies

1. What are good and bad ways to document a software project? (http://stackoverflow.com/questions/1796376/what-are-good-and-bad-ways-todocument-a-software-project) I'm responsible of finding a good way to document the software project I'm working on. What things are important to document? Should documentation of code and design mainly be in the code in the form of comments? Should we put text files or Word documents directly in the source control togetether with code? Should we use a wiki? Factors to think about include how easy it is for the current team to create the documentation, and how easy it is for other developers to find, correct and extend the documentation later. My experience from many projects is that developers tend to not write documentation because the system for writing it is too complex or developer unfriendly, and that after a few years, new developers can hardly find the little documentation that was written. I'm interested in what approaches you have used in similar projects. What worked well, what did not work well, and why? Some key facts about the project:

The platform is C# and .NET. We use Visual Studio and Team Foundation Server for source control and work item (task) management.

We use Scrum and test-driven development and are inspired by domain-driven design.

The software consists of a collection of web services and two GUI clients. Other clients are going to integrate with the web services in the future. The integration will be done by other developers on other teams (so the web services form a kind of API).

SharePoint is heavily used throughout the development environment. Most projects have a SharePoint site, including ours.

On our project's SharePoint site we currently have a bunch of MS Office documents on things like requirements, design, presentations for stakeholders etc. Keeping everything up to date is hard.

We also have a SharePoint wiki for the development team only, where we document things in an unstructured manner as we go along. Examples include how our build scripts are organized, our testing policy, coding guidelines.

The software is an in-house application in a fairly big financial institution. The software is developed by a team of six people over a period of ~1 year. The developers are consultants hired in for this project only, and will not be available to help in the future (unless the client decides to pay for it).

The client has few guidlines for how this kind of project should be documented.

2. How Much Documentation Do We Need? (http://pmtips.net/documentation/)

Detail is good. Too much detail is bad. One serves its purpose, the other wastes time and money. So how much is not enough, how much is too much, and how much it just right? How do we know? Every project needs documentation. Every project needs some level of status reporting. But what is the breakeven point between project expense and project benefit? And dont forget about customer satisfaction. Ive worked projects where the customer wanted to see everything on paper and other projects where they didnt e ven want a regular status report they felt it was overkill and a waste of time and money. Unfortunately, its not always obvious up front what the project needs and what your customer will want and will pay for. Theres no formulano ready-made answer. The obvious answers to the following questions to me are a definite YES: Should every project have weekly status meetings? Weekly team meetings? A detailed project schedule revised and delivered to everyone weekly? But on some very short projects or for some spendthrift clients, the answer may not be as clear as a definite yes. Lets look deeper and try to figure out what, in general, those basic necessities are:

What is critical? What is considered essential to document the project in the early phases and throughout the ongoing portion of the project? Is it dependent on the size of the project? Should it be? The answer is probably it depends and, ultimately, yes. What if youre doing a detailed Sharepoint 2013 migration project how much documentation is needed for that? Planning, creating planning documents, the amount of detail put into project documentation and the amount of review and approval all takes time and project budget dollars. A $10 million project needs extreme planning, documentation, and ongoing detailed status documentation for compliance, to cover your hind end, and to provide the necessary information to everyone working on the project and supporting it. Certainly, a $50,000 project may require a different level of documentation and ongoing status reporting or accountability. It is my belief that the essential documentation items and for any project small or large are the following:

A statement of work identifying milestones, deliverables, various key project dates, assumptions, and constraints. This document either drives much of the future planning documentation or takes the place of it depending on the project size.

Documented and signed off project requirements. The level of detail may depend on the size of the project but keep in mind that bad requirements are bad requirements no matter what size the project is and bad requirements can cause any size project to fail.

A detailed project schedule no matter how large or small the project is that is revised weekly and delivered weekly to the project team, the project customer, and senior management.

The existence of detailed and regularly scheduled status reporting. Weekly internal team meetings just to make sure that everyone remains on the same page and that the project remains on track. Weekly status meetings with the client even if they only last 10 minutes every week for a smaller project. What is expendable?

There are many more documents that can be put together either officially or unofficially on a project. The functional design document, the project charter, the project communication plan, the risk management plan, the disaster recovery plan, and the test plan to name a few. Certainly most of these need to exist in some form or another even if they are an email covering the topic on a very small project. All of these MUST exist on large, detailed, and long-term projects. Most of these can be handled somewhat informally on very small, low-visibility and low-criticality projects. For example, youre going to do some risk planning and issue tracking on every project probably documented as part of the ongoing project status reporting that is performed. But on very small projects, there likely wont be enough dollars in the planning phases of the project to cover the creation, review and approval of a formal risk management plan. That alone would likely cost $5k-$20k. Certainly not worth it for a project with a budget set at $50,000. Summary Its all about scalability. From the project managers standpoint, wed like every project to include standard documentation. Everything to should be repeatable, basically fit a general mold. But its not always practical. Just as the PM needs to recognize how to scale his own involvement to fit the projects budget constraints, likewise he must do the same with the documentation activities on the project. 3. Engineering and IT Insight - Bad project documentation: Break the habit (http://www.controleng.com/home/single-article/engineering-and-it-insight-badproject-documentation-break-thehabit/e5008880f9a7c31863c62f777d9116e2.html) Improve manufacturing IT, automation, or control projects by avoiding missing, incorrect, poorly written, or incomplete documentation. Dennis Brandl 01/22/2011 Think youre done with a manufacturing IT, automation, or control project? Check your documentation to avoid one of the worst bad habits of projects: Missing, incorrect, poorly written, or incomplete documentation.

Formal writing has been around since before 2800 BC, and with almost 5,000 years of experience, we should have worked out the best way to communicate knowledge. However, many projects use the equivalent of sitting around a campfire and telling stories as their primary method for communicating knowledge and reviewing designs. In modern projects the campfire is replaced by the glowing screen of a web meeting, but the concept is the same. Failure to document, missing documents, incorrect documents, poorly written documents, or the failure to review and correct documents are among the worst bad habits of unsuccessful projects. Documentation can be the bane of any project. A large percentage of failed projects have been blamed on bad, missing, or incorrect documentation. There are many reasons for this, but one major reason is that engineers are usually poor writers. There may be something in the engineers brain that is at odds with clear and effective writing skills, or it may be that engineers have not learned critical writing skills. Poor documentation habits are often accompanied by poor review habits. Many engineers dont even know how badly they write because their documents are reviewed for technical correctness but not for completeness, clarity, and readability. You know you have this problem if a reader knows less and is more confused after reading project documentation than before reading it. Whatever the reason for the lack of writing skills, many project engineers (and their IT equivalents) prefer to document concepts and knowledge through meetings and seminars. The result is that a lot of project knowledge is kept only in peoples heads. These projects may have generated a lot of documentation, and can often be drowning in documents, but they are starved for useable knowledge. For internal projects that are to be delivered to end users, there is no alternative to good user documentation and usable training manuals. In unsuccessful projects these documents are not part of the development plan but are planned for development after we finish the code. This is shortsighted behavior and will invariably lead to multiple problems later in the project, usually requiring extensive rework. Without development of these documents during the design, the usability of the product will not be known until after the code is complete. Many successful projects, including those that follow the Agile methodology, start with draft user guides and training manuals.

Technology transfer projects are especially prone to having bad documentation habits. These projects involve the technology transfer of automation systems, control strategies, recipes, and manufacturing definitions. The average technology transfer project involves shipping one or more engineers to the receiving site for weeks or months so they can install the new system and make it operational. During the project, the engineers will spend a lot of time rediscovering information that was not documented during the original development. Unfortunately, a large percentage of technology transfer projects end in failure because the original system cannot be reproduced at a different site. How do you know if your project has this bad habit? There are some signs to look for:

Frequent campfire equivalents for information exchange, such as having engineers travel to other sites to give information dumps

No user guides to help installation and maintenance of the system No one is assigned responsibility for creating user documentation Document reviews without review for readability and clarity No feedback mechanism for writers to improve their skills Much rework because someone missed the meeting where we talked about that.

To fix the bad documentation habit, your project should take the attitude if something isnt well documented, then you may as well throw it away, because you will eventually. No one wants to throw away work, so this attitude emphasizes the importance of usable and readable documentation. Breaking the bad documentation habit requires engineers and developers to improve their writing skills and extend their comfort zone to include the ability to write clearly and concisely. It also requires project managers to pay attention to the readability and usability of their projects documentation, not just the technical correctness. The bad documentation habit is a hard habit to break, but it must be broken to have a successful project. Few, if any, successful projects are without well-written and easily readable documentation. 4. Overcoming Inadequate Documentation (http://www.asis.org/Conferences/AM09/open-proceedings/papers/4.xml)

Authors Jinfang Niu University of Michigan 800 Blaine Ct. Apt# 1702, Schaumburg, IL 60173 Email: niujf@umich.edu Secondary data users need three types of knowledge to analyze secondary data: knowledge about data, background knowledge necessary to understand and interpret data, and data analysis skills. Part of knowledge about data is provided by the documentation of data. Background knowledge and data analysis skills are internalized as users' absorptive capacity. When documentation and their absorptive capacity are inadequate, users need to seek outside information to use secondary data. In this paper, causes of inadequate documentation were analyzed, why and how secondary users seek outside information were reported. Then based on the findings, implications about how to facilitate secondary data use were discussed. Introduction Secondary data use means analyzing data produced by other people. To enable secondary data use, data and knowledge about data need to be transferred from data producers to secondary users. Documentation plays an important role in transferring knowledge from data producers to secondary users. Previous research (Niu and Hedstrom, 2009) has found that perceived documentation quality varies with several characteristics of data and is weakly affected by users' absorptive capacity. In this paper, I will focus on how users overcome inadequate documentation by seeking information beyond what is provided with documentation. I will also provide some recommendations about how to facilitate secondary data use. Findings reported in this study are based on data collected for a larger research project. Details about the data collection method were reported in (Niu and Hedstrom, 2009). Here I briefly review it: I interviewed 13 secondary data users for 30 to 70 minutes each. The interviews were unstructured and exploratory. Secondary users were asked questions about their secondary data analysis experiences in general and their most recent experience with a particular dataset. Preliminary findings from the interviews informed the next step survey design. The formal survey started in May 2008. Each respondent was asked

about his or her most recent experience using a dataset produced by a different individual or entity. 1,260 surveys were sent out and 384 usable responses were received. The survey collected both highly structured quantitative data and open-ended qualitative data. Knowledge1 Necessary For Secondary Data Use Based on the kinds of information that users seek during secondary data use, I identified three types of knowledge necessary to analyze secondary data: knowledge about the data, background knowledge used to understand and interpret data, and data analysis skills. Below are some examples of the three types of knowledge.

Knowledge about data: what is the response rate and sampling frame for a particular survey? how are the missing responses treated?

Background knowledge: disciplinary consensus on how to use common types of data, how to determine whether or not to weigh variables from samples? which variable best captures certain concepts? how to interpret frequently occurring variables? how to handle specific measurement issues?

Data analysis skills: how to convert hierarchical data files into appropriate rectangular files? or how to construct new derived variables?

Part of knowledge about data is provided by documentation of data. The term "documentation" is used for knowledge about data recorded and transferred to secondary users that helps secondary users understand and use data. Here are exemplary documents that can be parts of documentation: codebooks (sometimes called data dictionaries), reports about the data collection project, data collection instruments, previous publications based on the data, user guides or handbooks, statistical manuals, data extraction software, programs making new variables based on the original data, original IRB materials, workflow for creating new datasets based on existing data, etc. Documentation plays an important role even when people involved in producing and documenting data are present in secondary data use. interviewee #1 struggled with inadequate documentation even though she was collaborating with the Principal Investigator of that dataset, because the research assistant who did most of the data collecting and documenting work had left the project. Interviewee #7 was part of the data analysis team for the National Survey of Child and Adolescent Well-being.

She was involved in writing project reports for that dataset. However, in her later research based on that dataset, she still needed to go back to the reports that she wrote for more information. Background knowledge and data analysis skills are accumulated through academic training and professional experiences. Unlike documentation, which is external knowledge, background knowledge and data analysis skills are internalized as part of secondary users' knowledgebase. I borrow the term "absorptive capacity" from Szulanski (1996) to refer to knowledge necessary to use secondary data and internalized by secondary users. Knowledge from documentation can be internalized and become a user's background knowledge. In those cases, users would be less reliant on documentation. This is most dramatic when a user has used the same dataset or the same data series many times. Why Do Users Seek Outside Information? The previous section tells us users rely on both external documentation and their internal absorptive capacity to analyze secondary data. Consequently, the inadequacy of either documentation or absorptive capacity could motivate users to seek outside information to fulfill their needs. In this paper, I use the term "outside information" to refer to knowledge and information that is necessary for secondary use but is missing from documentation or users' absorptive capacity. The adequacy of documentation can be measured on three dimensions: sufficiency, ease-of-use and accuracy. Documentation can be adequate enough so that users with sufficient absorptive capacity can use data solely based on documentation. Actually 19% of survey respondents were able to use secondary data based only on documentation. However, seeking outside information is often necessary. About half (46%) of surveyed users obtained outside information because the documentation did not contain the information they needed (not sufficient). Besides, hard-to-use documentation also turns users to other information sources. As one user said: "the code book contains the definitions of variables, but sometimes I think it is easier to pick up the phone. I got the codebook, but sometimes the variables are not clear to me. They do have a user manual, as well as statistical manual. Sometimes if I know someone who might know the answer, it is easier for me to pick up the phone." 12.5%

of surveyed users sought outside information because the documentation was hard to use. 31.4% of the survey respondents obtained outside information because other information sources or channels were immediately accessible, which is useful for understanding the following phenomenon: even though data produced for sharing are better documented than data produced for self-use (Niu and Hedstrom, 2009), users of data produced for sharing are not less likely to seek outside information than users of data produced for self-use. The reasons could be: producers who produce data for sharing tend to provide user assistance and make outside information more readily accessible. A few users sought outside information because they detected some errors in data and documentation (accuracy issues). People who did not seek outside information rate documentation as more sufficient (z=5.7, p=0.00)2 , easier to use (z=4.2, p=0.00) and of better overall quality (z=2.6, p=0.01) than users who did. Some information seeking is driven by absorptive capacity. Users with lower professional status5 are more likely to seek outside information (z=2.5, p=0.01). This is consistent with interview findings: students often get data analysis help from their advisors. As mentioned before, absorptive capacity is accumulated through academic training and professional experience. Therefore most of it is achieved before users start up using a particular dataset. As Interviewee #5 said: she would not be at the point of getting and analyzing data if she is not familiar with some terminology in the data. But often the case is that users did not expect something in a dataset during the process of analyzing it. For example, interviewee #6 used court records. Even though her field is criminal justice, sentencing and policing, she still needs to learn something about court process to use the data. To analyze a dataset using a new statistical method, interviewee #7 took a summer course offered by a data archive. Interviewee #5 received a lot of help from her advisor about how to read and interpret the data, and to select variables and conduct analysis while she analyze secondary data the first time. Here are more examples from the survey: "I did not receive information (about the data) outside of the documentation. What I received was additional information on how others used/interpreted the same data. This provided me with a deeper understanding of the data which I think was a benefit when I used the same data sets." "The information was not on the datasets itself but rather on operation of derived variables in previous

studies. For instance, how do you handle negative incomes and the like." "It was an analytic question more than a data-specific question." Besides the inadequacy of documentation and absorptive capacity, there are some social psychological reasons that users seek outside knowledge. Look at the following reasons that users sought outside information. "Working with others helps to bring the data alive." "Just want to get as much information as possible" "It was nice to talk to someone about the data instead of just read about it." "It is useful to talk with other secondary data users who are more knowledgeable about the data." "Website provided additional information that was useful for my analysis but I didn't need to use the website to use the data." There are also some users (11.6%) who obtained outside information not because they actively sought it, but because they happened to encounter that information. Causes of Inadequate Documentation Inadequate documentation is caused by two reasons. First, data are poorly documented because data producers are not willing to or are not capable of providing adequate documentation for secondary use. Second, documentation is inherently inadequate due to the nature of tacit knowledge and communication reduction. Researchers who produce data for self-use6 often are not willing to spend effort to document data for secondary use. Producers" incentives to share and document data depend on whether mutually beneficial or mandatory sharing mechanism exists. Simply speaking, A would be willing to share with B if B will reciprocate in a certain way. A would have to share with B if there is some pressure forcing him to do so, which could be cultural pressure from community norms, data sharing policies, or grant conditions. For example, a group of researchers used game players" data from Sony Online Entertainment to study the dynamics of network and group behaviors. When asked why Sony was willing to share the data with them, they answered because Sony expected to benefit from their research. One of our interviewees shared his data because his funding agency requires him to share, and he was afraid that if he did not share, his chances of getting future grants would be damaged. Without a mutually beneficial mechanism, even if mandatory sharing policy exists, data producers can "comply with

the letter of the law rather than its spirit, depositing poorly documented data that of little value" (Borgman, 2007, p. 242). Resource constraint is a factor that keeps data producers from creating good documentation. Most respondents of our 2006 survey7 expected that more time and financial support from funding agencies could be provided for documenting data. Some data producers complained that their grant was even insufficient to cover research needs, let alone creating documentation. By the time that the data are complete and the reports are delivered, time and funding are usually used up, with nothing left for documenting and sharing data. In addition, it is more difficult to document data for other people than for self-use, and that also challenges data producers' ability to provide adequate documentation for secondary use. According to Borgman (2007, p. 167), the effort required to explain one's data adequately increases as a function of the knowledge distance between data producers and users. Documenting research data for use by team members is more difficult than documenting it for personal use. Documenting it for off-site collaborators is more difficult still. Most difficult of all, however, is documenting for unknown future users, which is precisely the case for public data sharing. Another reason is the nature of tacit knowledge and communication reduction. Existing literature suggested the following types of tacit knowledge. (1) Knowledge that is technically difficult to articulate. Tacit knowledge is hard to formalize and communicate because it is deeply dwells in a comprehensive cognizance of the human mind and body (Polanyi, 1962). (2) Tacit knowledge that is sensitive and subtle, even though people may know implicitly, it is not appropriate to make them explicit. In talking about why groupware fails, Grudin (1993) said a priority-based meeting scheduler foundered because participants were reluctant to acknowledge publicly that some of their meetings were low priority. (3) Knowledge filtered out through communication reduction. Not everything can, or should be transferred. Some kind of reduction, and thus loss of complexity is inevitable (Strathern, 2005; Carlson and Anderson, 2007). Documenting data is necessarily a filtering process that only keeps the details that matter most to data producers. (4) Knowledge taken for granted by data producers. Data producers may unconsciously keep the details of their data collection and variable construction

processes and the particular quirks of the data in their memories and do not put them in writing, without realizing that secondary users do not know those details (Fienberg, Martin, Straf, 1985). My survey and interviews revealed other categories of knowledge that tends to be missing from documentation. (5) Informal knowledge. One user said: "People don't document why some of the numbers are funny, things that went wrong in the survey, etc." (6) Missing knowledge caused by mismatches between the concerns of data producers and that of data users. As one user said: "while you are using existing data, most of the time somebody collected it for a different reason. The failure that I had with the sentencing data was that whoever collected that data, for whatever reason, didn't need to know where the offenders came from. So they didn't record it." Where Do Users Seek Outside Information? I categorize knowledge transfer channels into three types based on the kinds of knowledge that can be transferred through them. One channel is the use of documents. Only explicit knowledge can be transferred in this manner. A second channel is interactive conversations, such as face-to-face or phone conversations, meetings, or email messages. Through this channel, a receiver might be able to capture some tacit knowledge through the facial expressions or tones of the sender, but knowledge transferred through this channel is primarily explicit knowledge that is verbalized and not formally documented. When documents are not sufficient to transfer knowledge, conversations may help the receiver to obtain more information or further clarification. A third channel is situated learning. A typical example is an apprentice working with his/her mentor in order to learn craftsmanship not only through language, but more importantly, by observation, imitation, and practice. Tacit knowledge that is technically hard to articulate or socially sensitive can be transferred through this channel. This rationale is used in analyzing the sources and channels where users obtained outside information. Table 1 is a list of information sources and the percentage of users who used each source for outside information. Please be informed that one user may seek information from several sources.

Table 1. Sources for outside information (N=353)9

Besides those main sources, other information sources include: using related datasets to check the integrity of the data used or for other reasons, publications based on similar data collected by different researchers, outside sources of scales used in the data set, alternative publications with similar information, newsletters mailing lists for users of the same data, relevant newspapers, etc. 64% of survey respondents obtained outside information from various kinds of documents. Based on our rationale, that kind of knowledge is explicit knowledge that can be incorporated into documentation, or at least pointed to from documentation. 68% of survey respondents sought outside information from other people. Some of those people work closely with secondary data users, such as mentors, advisors and colleagues. Some are strangers, such as other users of the same data on a mailing list, other data users or data producers found through Internet search, data producers who left contact information in documentation, data archivists where users obtained data. Users who obtained data from data producers are more likely to seek outside information from data producers (chi2=6.87, p=0.01) and websites of data producers (chi2=5.59, p=0.02). Among 239 users who obtained information from people, 80% obtained that information through email or telephone, 55% obtained that information through face-to-face conversations, 31.4% obtained that information by working

together with other people. 18.4% of users used all of the three channels. About half of the users (49%) used at least two channels. 36% only used email or telephone. 11% only used face-to-face conversations. 3% obtained knowledge only by working together with other people. For users who obtained outside information only through one channel, Table 2 shows the distribution of reasons why users sought outside information. The five letters represent five reasons why users obtained outside information. A and B are related to the adequacy of documentation. C and D are related to the convenience of information sources and channels. We can see several patterns from the table. First, people are more likely to obtain outside information through email and telephone when documentation is inadequate. Second, people are more likely to obtain outside information through face-to-face or working together when those channels are convenient. Third, people are more likely to obtain hard-to-document tacit knowledge through working together. This third pattern is consistent with our rationale that tacit knowledge is more suitable to be transferred through situated learning than through documents or interactive conversations. Among 21 users who sought outside information only because of tacit knowledge problems, 18 sought that information from people (17 through email and telephone, 10 through face-to-face conversations, and 3 through working together); 14 obtained outside information from various documents (websites and publications based on the datasets); 7 only obtained information from people, 3 obtained that information only from documents.

Table 2. Reasons for obtaining outside information (N=353)

A higher percentage of qualitative data users reported tacit knowledge problem than quantitative data users (chi2=3.3, p=0.07). The fact that hard-to-document tacit knowledge is transferred also through documents is consistent with the categories of tacit knowledge listed in previous section: tacit knowledge not only includes knowledge that is technically hard to articulate, but also knowledge that is social sensitive, informal, etc. Implications For Helping Secondary Use What I have reported so far can be summarized as the followings: Inadequate documentation is caused by two reasons. First, data producers are not motivated or not capable of documenting data well for secondary use. Second, documentation is inherently inadequate because of the tacit knowledge problem and communication reduction. When documentation is inadequate, users seek outside information to supplement documentation. However, inadequate documentation is not the only reason that users seek outside information. Users may seek outside information when documentation has no problems. They may seek outside information when their absorptive capacity is not ready for using the data. They obtain outside information about data due to convenient outside information sources and channels. They prefer to obtain information by socializing with people than reading documentation alone. Some users encounter useful information without actively seeking it. When seeking outside information, more than 60% of users turn to various documents, which can be easily

included in documentation or at least point to from documentation. More than 60% of users seek information from various people. These findings above have implications for strategies to help secondary data use. One way to help secondary data use is to improve users' absorptive capacity. Some data archives provide data analysis training for secondary users. Otherwise, we should rely on users' academic training and professional experience to improve their absorptive capacity. A second method to help secondary use is to provide more communication channels between data producers and secondary users, and among secondary users. More communication helps build collaboration relationships, makes outside information immediately accessible for secondary users, increases the chance of encountering information, and facilitates the transfer of tacit knowledge. Currently some data producers provide workshops to train data users and make them familiar with their data. There are also some mailing lists for users of the some datasets. Web 2.0 technologies such as Wiki pages also can be used to facilitate communication. A third method is to provide instructions to data producers and make sure those instructions are known and implemented by data producers. The data archive community has various tools and methods available to help data producers, such as the international standard Data Documentation Initiative (http://www.ddialliance.org/), guidelines provided by various data archives, and the idea that documentation should be incorporated into the whole life cycle of data. But many data producers are not aware of these instructions or do not implement them. Improving the awareness of these tools and methods may help data producers document data better for secondary use. A fourth approach is to provide incentives for data producers who are not motivated to document data well for secondary use. The Coase theorem (Frank, 2007, p. 539 and p. 543) can be applied here. Below are tentative and brief discussions about how Coase theorem can be applied to data sharing. According to the Coase theorem, when the parties affected by externalities 14 can negotiate costlessly with one another, an efficient outcome results no matter how the law assigns responsibility for damages. When there is a negotiation cost, efficient laws and social institutions are the ones that place the burden of adjustment to externalities on those who can accomplish it with least cost. Here is an example to show what the

theory means. A doctor and a candy maker are neighbors. The doctor's ability to examine patients was disturbed by the noise of machinery operated by the candy maker. Suppose the candy maker has access to a soundproofing device that eliminate all noise at a cost of A. the doctor has the option of avoiding the noise by re-arranging his office, which will cost B. If the negotiation of a private agreement between the doctor and the candy maker entails negligible cost, whether the legal system makes the candy maker liable for the noise doesn't affect the efficiency of the outcome for the society. When the negotiation of a private agreement between the doctor and the candy maker is not cost free, if A < B, making the candy maker liable for noise damage is more efficient for the society than otherwise. If A > B, not making the candy maker liable for noise is more efficient for the society than otherwise. Applying this to data sharing, poor documentation provided by data producers is a kind of noise, which puts data producers and secondary users in the same situation as the candy maker and the doctor. Data producers can solve the problem by taking time and effort to improve the quality of documentation. Secondary users can overcome inadequate documentation by seeking outside information, making compromises, tolerate uncertainties, etc. If the negotiation between the two parties is cost free15 , an efficient outcome results no matter how the law assigns responsibility for inadequate documentation. In other words, it is not necessary to make data producers liable for inadequate documentation. Making data producers liable does no good for the society versus if we just leave messy data and poor documentation for secondary users to deal with. If the negotiation cost between the two parties cannot be ignored, to achieve higher efficiency for the society, whether we should make data producers liable for poor documentation or not depends on which party can solve the problem with lower cost, which may vary with data producers. Three types of data producers tend not to be motivated to document data well:

1) private companies, for example, Sony Online Entertainment is a company who runs large online gaming environment. It keeps records about the behaviors of game players. But they do not sell those data for profit. Those records can be used by researchers to study some social or psychological issues;

2) government agencies who produce administrative records as by-products of their business process;

3) individuals and small research groups who produce data for their own research.

It may not be cost efficient for private companies and government agencies to spend more effort documenting data for secondary users who tend to be individuals and small research groups. In other words, if only one user or very few users need certain records produced by a government agency or a company. It will be more efficient to not make data producers liable for messy data and poor documentation and let the users take the cost in using data. But if a very large number of users need those data for research, it may be more costly for each individual user to clean up data and take various efforts to supplement documentation. Therefore it may be more efficient to make data producers liable for messy data and poor documentation when the data are wanted by a very large number of users. This actually explains why administrative records are often messy and poorly documented when they are obtained by individual researchers directly from government agencies, but often well documented when they are obtained from an intermediary organization. Administrative data obtained from a government agency by individual researchers are less likely to be used by a large number of users. Administrative records obtained from intermediary organizations are compiled for sharing and intend to be used by a large number of users. It is a different story for data producers who are individuals or small research groups. Users of those data are likely to be individuals or small research groups as well. Which party can overcome the externality of messy data and poor documentation may need to be decided on a caseby-case basis, or depends on how much policy makers value secondary data use. If policy makers value secondary users' cost to overcome poor documentation more than the third type of data producers' cost in improving data and documentation quality, under this value system, it would be more efficient to make data producers liable. Otherwise, it would be more efficient to let secondary users take the cost to use data. Suppose paying intermediaries to clean up data and improve documentation quality costs less than data producers to do the work themselves, Intermediaries, such as data archives, become a lower cost solution for data producers. Using intermediaries would

lead to a more efficient outcome than not using them. Actually, this is exactly what the National Institute of Justice (NIJ) is doing. NIJ requires its grantees to deposit data into a data archive at the end of their grants. Law enforcement is a coercive force and often involves some sort of punishment for non-compliance. The other way to motivate data producers to improve data and documentation quality is to use rewards. Appropriate rewards can establish mutual benefiting mechanism between data producers and secondary users, and change the situation that even though data producers take effort in preparing data for sharing, the benefit of sharing largely goes to secondary users. Effective punishments forces all data producers without plausible excuses to prepare and deposit data, which would make most data collected under public funds accessible to the public. This gives users' chances to verify the research findings of data producers, which would deter scientific fraud and misconduct. On the other hand, not all data sets will be used heavily (Niu and Hedstrom, 2007). Under the punishment scenario, even if the data is very unlikely to be used in the future, the data producer still needs to document and share data to avoid punishment. Enforcing uniform strong punishment on all data sets would cause the waste of resources. Unlike the coercive and uniform nature of punishments, rewards are inducive and selective. Rather than forcing researchers, rewards induce researchers to prepare and deposit data. Researchers who expect their data to be used by other people will be motivated to do better in data sharing. Data producers who do not expect their data to be used will not share data, which may be more efficient for the society. In this case, not all federally funded data are made available to the public, chances to deter scientific fraud decreased. Besides, data producers decide their effort in data preparation based on the expected future use of their data, which might be hard to anticipate. Acknowledgements This research is funded by the Rackham Research grant for dissertation and the Rackham one-term dissertation writing award from University of Michigan and NSF Award # IIS 0456022. I greatly appreciate the comments and instructions from Professor Margaret Hedstrom.

5. IMPROVING PROJECT DOCUMENTATION (http://www.apcc.gov.au/ALLAPCC/APCC%20PUB_Improving%20Project%20Do cumentation.pdf) Poor procurement and project management can often be traced back to insufficient planning and documentation, inadequate design briefs and a lack of clear understanding of the various roles and responsibilities. In addition, unrealistic expectations, inappropriate allocation of risk and inexperienced staff contribute to poor process and outcomes. Effective procurement strategies, skilled and knowledgeable client representatives are an important component for needed reform. This guide establishes a number of principles and protocols to guide practices of both the client and the consultant. The protocols follow the sequence of project establishment and progress through to tools and techniques during the design and documentation phases of a project. This guide is recommended for adoption by clients and design practitioners who seek to improve documentation. This guide is the beginning of a process of continuous improvement. It is complemented by demonstration projects being undertaken by contributing jurisdictions and web based information including case studies of good and bad practice, and tools such as checklists and templates. It proposes the measurement of outcomes to verify whether there is improvement and to assess the extent of improvement in key areas. It should also help identify opportunities for ongoing improvements to process and practice. Improved documentation standards are most likely to occur where there is recognition of the factors that are likely to lead to better project outcomes. It is recognised that the practice and behavior of clients as well as the disciplines adopted by project documentation teams will collectively contribute to the quality of service provided. An apparent decline in project documentation quality over the past few years was considered to be causing inefficiencies and costs in the construction process.

This concern led to the Australian Construction Industry Forum (ACIF) and the Australian Procurement and Construction Council (APCC) agreeing to undertake a joint project to identify the key issues for government as the client and buyer of services and the construction industry as the seller and supplier of services.

The Commonwealth Department of Industry, Tourism and Resources provided the financial support to enable the ACIF to commission research into issues relating to project documentation. The research undertaken by CSIRO to identify common concerns and possible solutions was completed in March 2002. The ACIF has worked with the APCC on a series of projects, each of which aims to improve understanding and encourage continuous improvement in the building and construction industry. The ACIF and the APCC outlined the following project objectives and strategic outcomes for improving project documentation: To review the current quality and standards of technical documentation in both public and private sectors on a national basis and to assess their impact on construction cost and time. To define the best practice principles in project documentation and their application within the construction industry. To define initiatives and develop a strategy for documentation improvement. To raise national awareness and promote shared solutions to good construction documentation. The CSIRO and the ACIF identified the following key areas of concern in project documentation as leading to design problems: Inadequate client briefs. Design details not known ie standards not clearly defined. Constructability problems. Statutory compliance problems. Time availability problems.

Consultants, as the suppliers of services where government is either the direct client or the project initiator, would like to see: Better agency front-end planning and better project briefs from the client. Better assessment of the complexity of work required. Allocation of appropriate fees and timelines commensurate with the complexity of the work to ensure all necessary work can be done within the budget and timelines. For this guide the definition of client is parties inviting the receiving tenders, for example project owner, project initiator, property manager or contractor in the supply chain. Five sets of protocols have been developed: Protocol 1 Client Brief & Project Establishment Establishment of well defined client brief comprising key drivers and parameters such as: budgets, functions, quality, sustainability, urban issues and commercial returns. Better articulation of requirements by the client equates to better consultant response. Client brief to include any requirements for document checking and coordination services (which will be reflected in consultants fees offered). Client may require additional advice in brief preparation, budgeting and programming, and engage specialist expertise, as in the case of highly complex projects. This may include engagement of facilities planners and/or independent cost advisors that may not necessarily be part of the project team. Clearly articulate client expectations of the consultant in the request for proposal and state criteria for selection. Clearly articulate the conditions of contract and obligations on the consultant i.e. quality control, assurances. Protocol 2 Consultant Selection

 Client recognition that consultant fees would be commensurate with the eff ort required and selection based on non-price and price criteria to establish value. Clients to inform themselves of reasonable benchmark fees (see the APCC document on selection of consultants) required for the services being requested. Ensure selection assessment practices are ethical and transparent. Client recognition that fees and premature commitment of work will increase the probability of inadequate documentation and claims.

Clients could consider prequalification of consultants with proven record of performance and base selection on previous performance assessments, thereby reinforcing the selection of the better performers. Clients may insist on demonstrable quality control consultants. Consultants to articulate the project methodologies including design approaches and quality controls in response to invitations to submit proposals. Primary consultants should select any secondary consultants on a value for money basis and submit with their proposals the rationale for selection of their consultant team. Protocol 3 Team Formation and Project Integration At the commencement of the project, client and project team should ensure that roles, responsibilities and obligations of all parties are clearly understood. Assumptions underpinning the project and key drivers for the project should be tested. Establish and agree a design and documentation review process including review points and agree milestones for client and project team sign-off. Develop a quality plan including procedures for communication, document control and coordination. Client may create obligations on consultants to report on risk and options for managing risk. Obtain approvals and sign off progressively throughout the project.

 Encourage project teams and clients to utilise tools to assist e.g. value management. Encourage establishment of integrated teams and articulate procedures for problem resolution. Encourage design and documentation teams to bring construction expertise to t he team to provide greater confidence e.g. early use of contractors on build-ability. Recognise that different parties bring different skills. Protocol 4 Quality Management Incorporating Project Implementation, Design and Documentation Actively consider total cost of project (over the life cycle) as part of the design and documentation process. Develop and agree upon a range of Quality Management Tools including checklists, review procedures and audit processes. The client and project team to consider the role of independent reviewer or value management. Consultants to provide advice on the quality of documentation that could be reasonably expected from the agreed resources allocated and timelines established for the period. Consultants to warrant that they have undertaken the design and documentation in a manner consistent with their quality plan. Use of technology by consultants to assist in documentation control and coordination. Project team to agree upon and nominate an experienced person responsible for documentation coordination. Quality plan to make provision for secondary consultants to be satisfied on the completeness of information supplied by the primary consultants. Obtain approvals and segmental sign off.

Protocol 5 Consultant Obligations and Functions Comply with code of ethics and professional conduct requirements concerning quality of documentation and offer fees commensurate with the effort involved. Advise the client on the adequacy of the brief and the risks associated with any inadequate allowance for proper documentation in both budgets and programs. Coordinate secondary consultants, obtain their sign-off on completeness of their documentation, and provide overall sign-off to the client that project documentation is comprehensive. Ensure version control of documents to secondary consultants. Create design and documentation coordination roles within project team.

CONCLUSION The ACIF and the APCC will continue to work cooperatively to encourage the adoption of the protocols identified in this guide. The ACIF and the APCC will work with interested stakeholders in the development of specific tools and techniques that will assist in their application. These protocols by clients and consultants are expected to improve project documentation within the building and construction industry. 6. The cost of bad documentation (http://cybertext.wordpress.com/2009/02/12/the-cost-of-bad-documentation/)

A couple of years back, fellow technical communicator Rahel Anne Bailie (over at Intentional Design Inc.) wrote an excellent piece about the real cost of poor documentation.

She had this to say: The cost of creating any documentation is often a prickly point with management. Outside of regulated industries, where a minimum standard for documentation quality is enforced, the quality of documentation ranges wildly from the abysmal to absurd to excellent.

Skimping on documentation quality is often rationalized away by claiming that users dont read it. The reality is that while customers dont read a document from front to back, they do refer to the document when theyre in trouble. And when they cant find that single, critical piece of information, their perceptions and expectations change. They stop using the documentation and revert to calling the vendors support line a far more costly alternative to looking up an answer because they assume that none of the needed answers will be found in the documentation. This also starts the viral communication chain word-of-mouth, forums, listserv, and blog posts, entries on complaint sites criticizing the product. While more techsavvy readers may identify the source of the problem as the documentation, consumers are more likely to think that the problem lies with the product itself, or see shoddy documentation as an extension of a shoddy product. The Consumer Electronics Association recognizes that the disconnect between product function and documented procedures is a significant contributor to their $10 billion-a-year product return problem.

Has much changed such Rahel wrote this?

An earlier (2002) piece by Dave Barry (Do not read while sleeping, reproduced in various US newspapers in 2008) suggested that: One big reason that consumers dont read manuals is that the typical manual starts out with 15 to 25 pages of warnings, informing you of numerous highly unlikely ways in which you could use the product to injure or kill yourself. So every year there are more huge product-liability awards, and every year manufacturers have to put more warnings in the owners manuals, and every year the radish-brains come up with newer, more-innovative ways to injure themselves.

He has a point

Another STC colleague of mine, Rich Maggiani, has written a one-page position paper on the Costs of Poor Communication. He states:

Financial statements do not carry a line item for these opportunity costs, which are relentless drains on your cash flow. The paper enumerates both common and specific examples, and identifies key consequences of poor communication: squandered time, wasted efforts, eroded loyalty, lost business, and of courselost revenue.

Most executives and managers understand how poor communication costs; what they do not realize is how big a role they play in this miscommunication. 7. Importance of documentation (http://itknowledgeexchange.techtarget.com/information-technologymanagement/importance-of-documentation/) I realized the importance of documentation many years ago when I joined an organization to head its IT function. The previous IT head had left the organization a couple of months ago. The managing director called me over and voiced his expectation. He told me that all ground work had been done for ordering new set of servers and application packages and that I should act upon it soon. I promised to take a look at the situation and revert with plans. However, when I sat in my department and rummaged through papers, I could not find much except notes ondiscussions with the vendor and details of configuration. For instance, there was no document showing an IT plan, applications to be developed / bought, functional areas to be covered, priority of tasks and justification for the equipment and software to be bought. When I went back to the boss expressing my helplessness in the absence of documentation, he was visibly

annoyed and refused to discuss further. I then spent the next three months drawing out fresh plans and submitted them for approval. Having learnt the lesson, I made it a point to always submit a handing over report to the management whenever I left any organization, which carried details on the IT set up, current status on various tasks, pending work, and the matters that would need attention in the following six months. Consequences of poor documentation Proper documentation is essential at every stage of our working and it doesnt have to wait for a specific occasion. Documentation is simply a habit and a discipline and contrary to what many think, it does not require great effort. Good practices speak of creating documentation alongside and not to wait for the entire work to be over. I have faced several embarrassing situations due to lack of documentation. In one case, my assistant misplaced documents relating to approvals and vendor negotiation thus attracting auditors comments for loss of control. Failure to record discussions and agreement with users has often lead to damning arguments during implementation stages. Not documenting system specs has got many of us in trouble. Absence of software specifications or incomplete specs makes many a developer code again rather than trying to rectify an earlier program. Lack of proper recording of approvals for user rights in the user profile can be a serious lapse and may cede ground for frauds to be committed. What constitutes documentation Documentation involves creating documents to record details / specification / events or storing and preserving documents that are relevant. They are important for the purposes of recording details of various activities, for retaining as evidence, for documenting policies & rules, for exercising control, preserving for posterity or as instruction for work to be done. Documentation can be on any

medium including paper, on disks, DVDs, or on common repositories accessible on the net. Types of documentation I would classify documents in the following few categories: General: Information systems plan, IT strategy, yearly budget, and the spends against the budgets, proposals for projects and their approvals, minutes of important meetings, periodic reports to management, etc. Commercial: Request for Proposal (RFP), Record of talks / negotiation with vendors, PO copies, correspondence, etc. Project documents: Requirements, statement of work, scope of work (SOW), software design and functional specification, system design and functional specifications, change management, error and enhancement tracking, user test and acceptance (UTA), and end-user manuals. Others: List of IT assets, network diagram, security policy and other policies, disaster recovery policies, and action steps, etc. When to start

I am told by many, that Indians are poor in documentation because of the legacy of the old Vedic period when thousands of lines of verses were carried through generations just by word of mouth. I do not however believe on that theory and strongly suggest that it is matter of habit. All IT service companies and consulting houses are immaculate in their documentation as it is a requirement dictated by the contract of services they have with their customers. It is however in the end-user companies that we face this problem. The question, when to start: well, it is now. It doesnt matter where we begin but we have to make a start and slowly build up our repository and should not be found wanting when any crisis strikes.

8. POOR DOCUMENTATION ALWAYS THE BIGGEST PROBLEM (http://www.minecraftforum.net/topic/1481936-poor-documentation-always-thebiggest-problem/) There are surely some fine mods out there but because documentation on how to install and use them is so poor it ends up being a nightmare of hours spent to gain nothing. I have a five year-old computer with built in graphics so I'd like to use Optifine -- but have spent hours getting nowhere. MagicLauncher says Optifine has 17 errors. Huh? I loaded another mod and MagicLauncher says there's nothing in it. Huh? It's nothing but frustration with this stuff. Then I try something "simple." I unzip "dynamic lights" mod into the minecraft file... but nothing happens. Good grief. I've updated the game and the mcpatcher over and over but that also does nothing.