Technical writing
Why technical writing is important
Writing tha help users solve problems with tecnologies and technical subject matter
1 Marketing
You have to sell your product
2 Gets the information out of your head
People will stop asking you for it
3 Gets the team on the same page
Documentation should be
- Essential: Document with just barely good enough detail
- Valuable: The benefit of having documnetation must outweight the cost of creating and maintaining it
- Timely: Documentation should be done in a just-in-time(JIT manner) when we need it
The writing process
Plan -> Research -> Write -> Review/Edit -> Launch
Document purposes
- Persuade readers to think or act a certain way
- Enable them to perform a task
- Help them understand something
- Change their attitude
The reasearch phase
- Interview subject matter experts(SMEs)
- Review existing documentation
- Use the software
The writing phase
Organize your content and ideas Create your writing plan, organize and order your ideas using list or categories
Write the first draft: Just write, follow your plan from step 1, don't worry too much about grammer, formatting or spelling, all type of things. You can get back later
Review and revise your own work
- Does the document fullfill its purpose
- Is anything missing?
- Can anything be taken out?
- What questions will the reader have? And answer them
- Is the writing easy to understand?
Reviewing/Editing phase
- Adjust or organize content
- Editing for style
- Editing for gramming and punctuation
Plan phase
Analyzing your audience:
- Who will be reading it?
Type of documents
Requirements
Identify what is to be built, and to verify we're meeting stakeholder'expectation
Design/Architecture
Defines how the system will be constructed, describing critical components and how they fit together
Code/Technical
Enable task completion and understanding
Test Plans/Test cases
Define the approach to testing; expose errors or demonstrate correct behaviour
End user
Enable task completion, provide support and troubleshooting
Writing tips and best practices
Accuracy
Fast is fine, but accuracy is everything
Deliverables
Requirements
User story
One or more sentences in everyday or business langugage that capture what a user needs to do Format: As a (type of user), I want (some goal) so that (some reason) Examples: As a (patient), I want (to receive an SMS message when my prescription is ready to pick up) so that (I can avoid unnecessary waiting at the pharmacy)
Traditional text-based requirements
Usecase
A list of actions or event steps, typically defining interactions between an actor and a system, to achive a goal
Software requirements specification(SRS)
Description of a software system to be developed(ties together requirements we've just talked about)
Design/Architecture
Introduction
- References to other pertinent documents
- Definitions of important terms, acronyms and abbreviation Purpose: This document defins the design of the Pharmalantalert system, as set forth in the Software Requirements Specification(SRS). It contains details of the web application as well as the mobile app, including system architecture, component design and data design.
Scope:
- A brief description of what the system will do
- benefits, objectives and goals of the system
- Associated risks Intended audience:
- This doucument is intended to be used by the software development team, including developers and project managers.
Design goals and rationale: Explain why you use this design instead of others For example: The web application will be designed using the MOdel View Controller(MVC) architectural style.
The reasons for implementing MVC architecture are twofold. First, allows information hiding and seperation of concerns. This allows for high cohesion and low coupling. The system is therefore lighter, more secure and easier to maintain debug
Also includes:
- Assumptions and depedencies
- Constraints
- Goals and guidelines
- Development methods
System architecture
Detailed system design
- Design patterns and techniques
- Modules, classes, files
- Data structures
- Algorithms
- Interfaces
Class diagram
Sequence diagram
Data design
- Fequency of updates
- Security requirements
- Receovery
- report Generation
- Iterfacing systems
Readme
Until you've written about your software, you have no idea what you'll be coding
Write your README before your code
Test plans and test cases
Test scenario and test cases
End user documentation
Documents the differences between two versions of the same software(v1 & v2)
