User talk:Tsunami.waves2040

software documentation-material
Software Documentation or Source Code Documentation is written text that accompanies computer software. It either explains how it operates or how to use it. In fact, the term software documentation means different things to different people. This article describes the term as used by the largest groups of users. Contents •	1 Types of Documentation •	2 Architecture/Design Documentation •	3 Technical Documentation •	4 User Documentation •	5 Marketing Documentation •	6 Tools for architectural, design and technical documentation •	7 Software engineering and documentation methodologies •	8 See also

[edit] Types of Documentation Documentation is an important part of software engineering that is often overlooked. Types of documentation include: •	Architecture/Design - Overview of software. Includes relations to an environment and construction principles to be used in design of software components. •	Technical - Documentation of code, algorithms, interfaces, and APIs. •	End User - Manuals for the end-user, system administrators and support staff. •	Marketing - Product briefs and promotional collateral. [edit] Architecture/Design Documentation Design documents tend to take a broad view. Rather than describe how things are used, this type of documentation focuses more on the why. For example, in a design document, a programmer would explain the rationale behind organizing a data structure in a particular way, or would list the member functions of a particular object and how to add new ones to the code. It explains the reasons why a given class is constructed in a particular way, points out patterns, and even goes so far as to outline ideas for ways it could be done better, or plans for how to improve it later on. None of this is appropriate for code documents or user documents, but it is important for design. Architecture documentation is a special breed of design documents. In a way, architecture documents are third derivative from the code (design documents being second derivative, and code documents being first). Very little in the architecture documents is specific to the code itself. These documents do not describe how to program a particular routine, or even why that particular routine exists in the form that it does, but instead merely lays out the general requirements that would motivate the existence of such a routine. A good architecture document is short on details but thick on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents. Another breed of design docs is the comparison document, or trade study. This would often take the form of a whitepaper. It focuses on one specific aspect of the system and suggests alternate approaches. It could be at the user interface, code, design, or even architectural level. It will outline what the IS situation is, describe one or more alternatives, and enumerate the pros and cons of each. A good trade study document is heavy on research, expresses its idea clearly (without relying heavily on obtuse jargon to dazzle the reader), and most importantly is impartial. It should honestly and clearly explain the costs of whatever solution it offers as best. The objective of a trade study is to divise the best solution, rather than to push a particular point of view. It is perfectly acceptable to make no conclusion, or to conclude that none of the alternatives are sufficiently better than the baseline to warrant a change. It should be approached as a scientific endeavor, not as a marketing technique.. [edit] Technical Documentation This is what most programmers mean when using the term software documentation. When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. This documentation is usually embedded within the source code itself so it is readily accessible to anyone who may be traversing it. This writing can be highly technical and is mainly used to define and explain the APIs, data structures and algorithms. For example, one might use this documentation to explain that the variable m_name refers to the first and last name of a person. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them. Often, tools such as Doxygen, javadoc, ROBODoc, POD or TwinText can be used to auto-generate the code documents—that is, they extract the comments from the source code and create reference manuals in such forms as text or HTML files. Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class. Many programmers really like the idea of auto-generating documentation for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to his code, and can use the same tools he used to create the source code, to make the documentation. This makes it much easier to keep the documentation up-to-date. Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the documents nightly). Some would characterize this as a pro rather than a con. Donald Knuth has insisted on the fact that Software documentation can be a very difficult afterthought process and has been advocating Literate programming where documentation is written in the same time as the source code and extracted by automatic means. [edit] User Documentation Unlike code documents, user documents are usually far divorced from the source code of the program, and instead simply describe how it is used. In the case of a software library, the code documents and user documents could be effectively equivalent and are worth conjoining, but for a general application this is not often true. On the other hand, the Lisp machine grew out of a tradition in which every piece of code had an attached documentation string. In combination with strong search capabilities (based on a Unix-like apropos command), and online sources, Lispm users could look up documentation and paste the associated function directly into their own code. This level of ease of use is unheard of in putatively more modern systems. Typically, the user documentation describes each feature of the program, and the various steps required to invoke it. A good user document can also go so far as to provide thorough troubleshooting assistance. It is very important for user documents to not be confusing, and for them to be up to date. User documents need not be organized in any particular way, but it is very important for them to have a thorough index. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do and should be free from undocumented features. There are three broad ways in which user documentation can be organized. A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks. A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. The final type of organizing principle is one in which commands or tasks are simply listed alphabetically, often via cross-referenced indices. This latter approach is of the greatest use to advanced users who know exactly what sort of information they are looking for. A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two It is common to limit provided software documentation for personal computers to online help that give only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer. [edit] Marketing Documentation For many applications it is necessary to have some promotional materials to encourage casual observers to spend more time learning about the product. This form of documentation has three purposes:- 1.	To excite the potential user about the product and instill in them a desire for becoming more involved with it. 2.	To inform them about what exactly the product does, so that their expectations are in line with what they will be receiving. 3.	To explain the position of this product with respect to other alternatives. One good marketing technique is to provide clear and memorable catch phrases that exemplify the point we wish to convey, and also emphasizes the 'ihio hgogure of the uses and capacities of the program than anything else provided by the manufacturer •	How may we contact you? Comments, questions, and suggestions are welcome. Please send them as e-mail to: support@smidgeonsoft.com •	How often are your programs updated? This depends on where my attention and interest is focused. I use my utilities as part of my daily activities. If an idea strikes me or something just does not seem to work correctly, I often interrupt my work to enhance my stuff and then return to the interrupted work to see if the enhancement or new feature works. My software is very much a representation of how I work and what similar programs should offer. •	Why don't you supply more program documentation? I don't supply program documentation because it is a PITA and often a permanent crutch. My software should encourage one to explore and experiment with the many configuration options and the rich context-sensitive menu structure. If it does not, I have missed my target. Much of what you see here is not meant for "beginners"; but since we were all beginners at one point, I hope that by using my programs, one will have help in moving past the beginner phase. •	Why are there so many PEBrowse programs, and which one should I be using? The three PEBrowse programs share large amounts of code, but perform distinct activities. PEBrowse Professional, the static analyzer and eldest, allows you to examine any Windows Portable Executable file (including system drivers) offline and not in the middle of some debugging session. That domain is reserved for the PEBrowse Professional Interactive debugger, which contains most (but not all) of features found in the PeBrowse Professional disassembler but brings powerful additions to the analysis and debugging of an active program. The latest addition to the PEBrowse family, PEBrowse Crash-Dump Analyzer, in many ways acts and feels like the debugger, but instead of a live target examines information collected in a mini-dump or crash-dump file from a dead process.

•	What is a "Smidgeon"? Smidgeon was my dear puppy-dog (a Sheltie) that passed away in 2001. She will always remain "my poopee" in my heart and memory and will be immortalized by her presence on the web.

Project Life Cycle Guide

Site Design Goals: Our first step is to listen to your ideas and website preferences. Together we will establish measurable goals for your site. Research, Assessment & Design: We will review sites that you like as well as your existing marketing materials to assist us in identifying your preferred website design style. Reviewing samples of our web designs may be helpful at this stage.

Site Architecture & Content: We'll consider your content preferences and create a site architecture map to visually demonstrate how the site content and structure will be organized. We also use a wire frame to help you understand how web pages work and where your content fits in.

Design: We design a proposed Web homepage, 2nd and 3rd level designs that define the "look and feel" for the entire site. We will refine the designs to your specifications. Content: In parallel with the design process, you will be gathering content for your new website.

Web Programming & Site Build-Out: Upon approval of the final site design, and content, we will incorporate any supplied photos and graphics you wish implemented and complete the entire site at one time based on the approved site architecture. Quality Assurance (QA) Testing: Upon completion of the website build-out, we will post the website to our staging site for your review.

After launch: we recommend an aggressive search engine marketing campaign to get you ranked high in the engines, and a monthly maintenance program to ensure your site stays current and "fresh".

Accessibility Guidelines for Web Pages The School District of Greenville County has a responsibility to set a standard for compliance with federal and state accessibility initiatives. The Americans With Disabilities Act of 1990 and other legislation direct us to accommodate people with visual, auditory, physical/motor, and cognitive/language disabilities. When applied to the Web, accessibility includes consideration for people with physical and/or cognitive disabilities. While not all web pages can be made totally accessible, our goal is to make District web sites as accessible as possible by emphasizing content and providing information on web pages designed with accessibility in mind. Examples of Disabilities to Be Considered Visual Disabilities Blindness - no sight. May use voice-output software or refreshable Braille hardware. Low vision - some sight. May use screen-enlarging software. Color blindness. Need high contrast. Most typical forms of colorblindness are the inability to distinguish between red and green, or blue and green, or blue and yellow; some people see panchromatically (black and white only). Auditory Disabilities Deafness - no hearing. Rely on text and graphics only. Hard of hearing - some hearing. May use sound-enhancing peripherals. Physical/Motor Disabilities Difficulty with detailed manipulation of input devices such as a mouse. Problems holding down multiple keyboard keys simultaneously. Cognitive/Language Disabilities Difficulty with spatial reasoning and/or visualization skills. Conditions that cause difficulty reading and/or understanding written text, such as dyslexia. Web Page Design Criteria Maintain a simple, consistent page layout, including positioning of navigational aids throughout documents and document groups. Use standard, universally recognized HTML tags. Use large, commonly understood navigation scheme. Use meaningful terms for hyperlinks. Provide short, simple and meaningful alternative text for all graphical features. Keep backgrounds simple and of high contrast to allow easy viewing of content. Avoid low contrast color combinations or colors that may not be recognized by lower resolution screens. Do not use frames pages. If used, provide alternative page versions. Provide text-based delivery alternatives for as much information as possible. Do not rely solely on special formats (e.g., Adobe Acrobat) that cannot be read by text and voice systems. Provide transcripts, descriptions or subtitles for video and audio files to assist people with visual and hearing disabilities. Test pages on a variety of Web browsers (at least Netscape Navigator and Internet Explorer) and at a variety of screen resolutions. Test pages on small screens to ensure the page does not bleed off the screen. Avoid parallel columns, as voice output systems read across the screen (i.e., jumps from column to column). Design the page so the user does not have to scroll from left to right to see the entire page. For More Information Trace Research and Development Center (UW-Madison) Web Content Accessibility Guidelines World Wide Web Consortium Bobby, Center for Applied Special Technology Yuri Rubinsky Insight Foundation US Department of Education's Requirements for Accessible Software Design Center on Information Technology Accommodation