Writing It Down: Documentation and Communication Best Practices

UPI Study › Courses › System Analysis and Design › Free lessons › Lesson 7.2 Free with a free account

Writing It Down: Documentation and Communication Best Practices

System Analysis and Design · Chapter 7: Implementation, Testing, and MaintenanceSection 7.2 · lesson 47 of 698 min · free with a free account

← Inside Application Development: Internal and External WorkflowsNext lesson: Programming Essentials: Writing, Testing, and Debugging Code →

Earn 3 college credits for System Analysis and DesignRecommended for credit by NCCRS · Computer Science 390 · self-paced · one payment, lifetime access
Enroll in System Analysis and Design · $250 →Download the syllabus (PDF)

In this lesson

Documentation types, standards, keeping docs current, and team communication.

  • Identify the 4 major types of system documentation, and what each is for
  • Explain why documentation standards matter, and what one covers
  • Describe practical ways to keep documentation current
  • Identify communication practices that support good documentation

Transcript

Everything said in the video, section by section (1,103 words). Read along, or search it.

Implementation, Testing, and Maintenance

Writing It Down

A system that works, but that nobody understands, is a system in trouble. This section is about writing things down well. We will look at the four types of documentation a system produces, and the standards that keep them consistent. Then how to keep documentation current as the system changes, and the team habits that produce good documentation almost for free.

Figure 7.2a

4 Types, 4 Different Readers

A system produces several distinct kinds of documentation over its life. Each is aimed at a different reader, with a different question in mind. Here they are, arranged from the most internal and technical, on the left, to the most external and user-facing, on the right. System documentation, and program documentation, are written for developers. Operations documentation, and user documentation, are written for the people running or using the finished system. Confusing the four, or trying to make one document serve every audience at once, is a common source of documentation nobody finds useful.

The 4 Types

Audience and Contents

Let's look at each type in turn. System documentation is for developers and architects who need the system's overall design. It holds architecture diagrams, data models, and interface specifications. Program documentation is for developers who need to read or modify a specific piece of code. It holds inline code comments, module and function descriptions, and readme files. Operations documentation is for the I T operations and support staff who keep the system running. It holds installation steps, backup and recovery procedures, job schedules, and troubleshooting guides. And user documentation is for end users doing their own work with the system. It holds user guides, quick-start guides, in-app help screens, and F A Qs.

Telling Them Apart

Same Audience, Different Vantage Points

The four types fall into two pairs, and each pair is easy to confuse. System and program documentation both serve developers, but at different levels of detail. System documentation explains how the pieces fit together. Program documentation explains how one specific piece works internally. Operations and user documentation both serve people working with the finished system, but from very different vantage points. Operations is about keeping the system alive. User documentation is about getting a task done with it. So, a developer wants to know why one function returns an unexpected value. Which type should they open? Program documentation. The question is about the code itself, not the system's overall architecture.

Documentation Standards

Consistent, Whoever Wrote It

A documentation standard is an agreed set of conventions for how documentation is written, organized, and formatted. The goal is that a document reads consistently, no matter who on the team wrote it. Without a shared standard, documentation quality simply tracks whichever person happened to write each piece. And a reader has to relearn the structure every time they open a new document. The payoff shows most clearly when someone new joins the team. Or when an unfamiliar document has to be trusted under time pressure. A consistent standard means the reader already knows where to look, without first learning each author's personal habits.

What a Standard Covers

6 Standard Elements

A typical standard covers six elements. Naming conventions set how documents, sections, and files are titled, so related material is easy to find. Required sections, or templates, set what every document of a given type must include, such as a purpose statement, or a revision history. Versioning sets how a document's version is tracked, and tied to the version of the system it describes. Formatting and style keep heading levels, terminology, and tone consistent. Storage location sets where documentation lives, so it is in one known place, rather than scattered across emails and chat messages. That matters as much as formatting. A beautifully formatted document is useless if no one can find it. And review and approval set who checks a document before it is published or updated, and what that check covers.

Keeping Documentation Current

Outdated Is Worse Than None

Documentation that has drifted out of date is often worse than no documentation at all. A reader trusts it to reflect the system as it actually is today. Five habits keep that drift from building up. First, update the documentation as part of the same change, rather than as a separate task for later. Then it never gets forgotten once the code ships. Second, make it an exit criterion. A work item does not count as done until its documentation is updated, which gives it the same priority as the code. Third, assign clear ownership, so gaps get noticed and fixed, rather than assumed to be someone else's job. Fourth, schedule periodic reviews, to catch drift that slipped through, before a reader relies on the outdated version. And fifth, retire outdated documentation. Archive the documents for a removed feature, so they cannot confuse a future reader.

Team Communication

Documentation as a Byproduct

Good documentation is rarely produced by one dedicated writing effort. It is usually a byproduct of communication habits the team already has. Four practices make that byproduct reliable. Decision logs capture not just what was decided, but why. The reasoning survives, even after the people in the room have moved on. Written summaries of verbal discussions. A quick call is fine, but anything worth remembering gets a short written record afterward. Code review comments and pull request descriptions explain why a change was made, not just what changed. They were never written as formal documents, but they live beside the code, where they can be searched, and they last. And a single, shared location keeps it all in one known place, rather than split across email, chat, and personal notes. None of this needs extra meetings. It mostly means writing down the decisions the team is already making out loud.

Key Terms

The Vocabulary of This Section

Let's lock in the key terms. System documentation explains how the pieces fit together. Program documentation explains how one piece works. Operations documentation gives I T staff what they need to keep the system running. User documentation gives end users guides and help for doing their work. A documentation standard is an agreed set of conventions for writing, organizing, and formatting documents. An exit criterion is a condition a work item must meet before it counts as done. And a decision log records what was decided, and why.

Key Takeaways

What to Carry Forward

To pull this together. System, program, operations, and user documentation each serve a different reader, from developers to end users. A documentation standard covers naming, required sections, versioning, formatting, storage location, and review, so quality does not depend on who wrote a document. Documentation stays current when updating it is part of the same cycle as the system change, not a task for later. Decision logs, written summaries, and code review comments turn everyday team communication into a lasting, findable record. And outdated documentation is often worse than none at all, because readers trust it to reflect the system as it really is.

About System Analysis and Design at UPI Study

System Analysis and Design (Computer Science 390) is a self-paced online course of 69 video lessons in 9 chapters, from the analyst's role and requirements to UML modeling, interface and database design, testing, maintenance and project management. It carries a NCCRS credit recommendation for 3 semester credits.

Every lesson transcript is free on pages like this one, and the videos are free with a free UPI Study account. Enrolling adds a practice quiz after each lesson, the graded work and final exam that earn the credit, lifetime access, and an official transcript on completion. UPI Study has helped over 130,000 students with college credits. ACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities.

Enroll now → Course details Download the syllabus All Computer Science courses Every course with PRO →

Compare: Software Engineering vs Systems Analysis

Why take it here

Why students take System Analysis and Design with UPI Study

From business problem to working systemSystem Analysis and Design teaches how analysts study a business need and turn it into a system design: requirements, UML and data-flow models, interface and database design, implementation and project management. It is a core course in information systems and IT degrees.
Credit at a fraction of the priceThe same 3 credits can cost $750 or more at a US college. Here it is one payment, self-paced, with lifetime access.
Finish your degree soonerTransfer credits reduce the courses you still owe, so you can graduate earlier or lighten a heavy semester.
Strengthen an applicationA completed college-level course on an official transcript shows admissions and scholarship committees you can do the work.
Study on your own scheduleNo start dates, no deadlines. Watch the lessons, practice, and take the final when you are ready.
130,000+students helped with college creditsACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities.

Where the credit goes

Universities that work with NCCRS

System Analysis and Design carries a NCCRS credit recommendation. These universities work with NCCRS; some are UPI Study's signed partners. ACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities.

Thomas Edison State UniversityThomas Edison State UniversitySigned partnerUniversity of the PeopleUniversity of the PeopleSigned partnerCharter Oak State CollegeCharter Oak State CollegeSigned partnerStrayer UniversityStrayer UniversitySigned partnerColumbia Southern UniversityColumbia Southern UniversitySigned partnerIndiana TechIndiana TechSigned partnerPenn StatePenn StateWorks with NCCRSSouthern New Hampshire UniversitySouthern New Hampshire UniversityWorks with NCCRSSUNYSUNYWorks with NCCRS +many more cooperating universitiesFind my college →

Find my college → Not listed? Ask Athena in the corner of this page, or book a 15-minute call.

FAQ

Questions students ask us

About Writing It Down: Documentation and Communication Best Practices

What are the four types of system documentation?
The four types are system, program, operations, and user documentation, each written for a different reader. System documentation gives developers and architects the overall design, such as architecture diagrams and data models. Program documentation explains specific code through comments and readme files. Operations documentation helps IT staff install, back up, and troubleshoot the system, and user documentation helps end users get their work done.
What is the difference between system documentation and program documentation?
System documentation explains how the pieces of a system fit together, while program documentation explains how one specific piece works internally. Both serve developers, but at different levels of detail. A developer puzzled about why a function returns an unexpected value should open program documentation, such as inline comments or a module description, because the question concerns the code itself rather than the architecture.
What does a documentation standard usually cover?
A documentation standard usually covers naming conventions, required sections or templates, versioning, formatting and style, storage location, and review and approval. Its purpose is to make every document read consistently, whoever wrote it. That helps most when someone new joins the team or an unfamiliar document must be trusted under time pressure. Storage location matters as much as formatting, because a document no one can find is useless.
How do you keep software documentation up to date?
Documentation stays current when it is updated as part of the same change as the code, not as a later task. Making updated documentation an exit criterion for calling a work item done gives it equal priority. Clear ownership, periodic reviews, and archiving documents for removed features also help. Outdated documentation is often worse than none, because readers trust it to describe the system as it is today.

About the System Analysis and Design course

How many college credits is System Analysis and Design?
System Analysis and Design (Computer Science 390) carries a NCCRS credit recommendation for 3 semester credits. ACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities.
How much does System Analysis and Design cost and what is included?
$250, paid once, with lifetime access: all 69 video lessons, a practice quiz after each, the graded work and final exam, and an official transcript when you finish. Students who want several courses choose UPI Study PRO instead.
Which universities accept UPI Study credits?
UPI Study has signed partner agreements with universities such as Thomas Edison State University, University of the People and Charter Oak State College, and works with universities such as Penn State, SNHU and SUNY. ACE and NCCRS have over 2,100 cooperating colleges that will consider accepting credits; the final decision is with the universities. Use "Find my college" on this page to check yours.
How long does System Analysis and Design take?
It is self-paced with no deadlines. The 69 lessons total about 9 hours of video; most students add reading and practice time and finish in a few weeks to a few months, on their own schedule.
How are the exams done?
Quizzes and assignments are online in the course. The final exam is taken online with proctoring; a person on the UPI Study team checks assignments, usually within two days.
How do my credits reach my college?
When the course shows 100% complete, request the official transcript from your dashboard. It is sent to the college you name, and you can send it to more than one. Check your college first with "Find my college" on this page, or ask Athena.

Ready for the full course? Earn 3 credits in System Analysis and Design.

69 video lessons, a quiz after each one, and the graded work that earns the credit. Recommended for credit by NCCRS.

Enroll in System Analysis and Design →Download the syllabusEvery course with PRO →
System Analysis and Design
3 credits · NCCRSEnroll →