Moving from User Documentation to Developer Documentation
-
Upload
amruta-ranade -
Category
Engineering
-
view
308 -
download
3
Transcript of Moving from User Documentation to Developer Documentation
![Page 1: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/1.jpg)
1Amruta Ranade
Moving from User Documentation
to Developer Documentation
![Page 2: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/2.jpg)
What are Developer Docs
2
![Page 3: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/3.jpg)
User Docs Vs. Dev Docs
3
![Page 4: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/4.jpg)
4
![Page 5: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/5.jpg)
User documentation
5
![Page 6: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/6.jpg)
Developer documentation
O What is the format of the email?
O How is the message encapsulated to form the message packet? Description of the headers and metadata
O How is the message packet converted into a bit stream?
O How does the Client notify the Server that it wants to send an email
O How does the Client connect to the Server?
O Which protocol is used?
O How does the Server look up the recipient's address?
O How does the Server figure out the recipient’s Email Server?
O ….
6
![Page 7: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/7.jpg)
User Docs Dev Docs
7
O What is the format of the email?
O How is the message
encapsulated to form the
message packet? Description of
the headers and metadata
O How is the message packet
converted into a bit stream?
O How does the Client notify the
Server that it wants to send an
O How does the Client connect to
the Server?
O Which protocol is used?
O How does the Server look up the
recipient's address?
O How does the Server figure out
the recipient’s Email Server?
One snippet of a User document corresponds
to multiple Dev documents ..
![Page 8: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/8.jpg)
Why do we need Dev Docs?
8
![Page 9: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/9.jpg)
User Docs Dev Docs
9
Resources: One resource to
document a feature
Resources: More than one
resource depending on the
technical depth of the feature
When: After the feature is
designed
When: Before the feature is
designed
Written for:
End-users
Support
Written for:
Developers
QA
Tech Writing
Support
Sales and Marketing
Project Management
![Page 10: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/10.jpg)
Types of Dev Docs
10
![Page 11: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/11.jpg)
API Docs
11
![Page 12: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/12.jpg)
What is an API
12
![Page 13: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/13.jpg)
Example of an API Doc
13
![Page 14: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/14.jpg)
Components of an API Doc
O Overview: Explain what advantages developers have in using the platform, and in some cases, provide an architectural description of the platform.
O Getting started: Help the developer get started, in the form of step-by-step tutorials or simpler walkthroughs.
O Sample code: Provide well-commented code samples that developers can build on.
O Reference material: Provide detailed information about each class, member, function or XML element.
14
![Page 15: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/15.jpg)
Resources
O Tom Johnson –
http://idratherbewriting.com/
O Sarah Maddox – API Technical Writing
http://www.slideshare.net/sarahmaddox/a
pi-technical-writing
O A Coder’s Guide to Writing API
Documentation –
http://msdn.microsoft.com/en-
us/magazine/gg309172.aspx
15
![Page 16: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/16.jpg)
Software Architecture Docs
16
![Page 17: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/17.jpg)
What is Software Architecture“Software architecture is the software’s fundamental
organization, embodied in its components, their
relationships to each other and to the environment, and
the principles guiding its design and evolution.”
17
![Page 18: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/18.jpg)
How do you document
a Software Architecture
Software architecture is documented in terms of views.
To understand views, consider an architect designing a
building…
18
![Page 19: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/19.jpg)
19
![Page 20: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/20.jpg)
Understanding Views
Just as a building architect might create
wiring diagrams, floor plans, and elevations
to describe different facets of a building to
its different stakeholders (electricians,
owners, planning officials), so an IT architect
might create physical and security views of
an IT system for the stakeholders who have
concerns related to these aspects.
20
![Page 21: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/21.jpg)
Context ViewStart from scratch and build the story of the evolution of
the product to the Big Picture
21
![Page 22: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/22.jpg)
Context View
22
00010011101
![Page 23: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/23.jpg)
Context View
23
![Page 24: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/24.jpg)
Functional and
Non-functional ViewWhat does the software do?
24
![Page 25: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/25.jpg)
Functional View Non-functional View
25
Key functions of the system:
O Activation
O Authentication
O Configuration
O Send and receive emails
O Send attachments
O Send emails to multiple users
O Chat
O Video Chat
O Group Chat
O Send email on behalf of someone
O Signature
O Encryption
O Folder structure
Examples:
O Performance ( latency and throughput)
O Scalability (data and traffic volumes)
O Availability (uptime, downtime, scheduled maintenance, 24x7)
O Security (authentication, authorisation, data confidentiality)
O Flexibility
O Monitoring and management
O Reliability
O Accessibility
![Page 26: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/26.jpg)
Logical ViewDrill down to the components and connections
26
![Page 27: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/27.jpg)
Components
27
O Message
O Composition
O Headers
O Metadata
O Email Client
O Component to format
the message
O Component to submit
message to server
O Component to encrypt
the message
O Outgoing Mail Server
O SMTP Server
O Incoming Mail Server
O POP3 Server
O Protocol
O HTTP
O Email Storage
O Contact Database
O Ports
![Page 28: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/28.jpg)
Process ViewWorkflow for each task
28
![Page 29: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/29.jpg)
Process View
29
High-level workflow
![Page 30: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/30.jpg)
Process View
30
High-level workflow
Detailed workflow
![Page 31: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/31.jpg)
Design ViewDefine the details of each component
31
![Page 32: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/32.jpg)
Design View
Email ClientO Message composition
Email clients usually contain user interfaces to display and edit text. Some applications permit the use of a program-external editor.
The email clients will perform formatting according to RFC 5322 for headers and body, and MIME for non-textual content and attachments. Headers include the destination fields, To, Cc, and Bcc, and the originator fields From which is the message's author(s), Sender in case there are more authors, and Reply-To in case responses should be addressed to a different mailbox. To better assist the user with destination fields, many clients maintain one or more address books and/or are able to connect to an LDAP directory server. For originator fields, clients may support different identities.
Client settings require the user's real name and email address for each user's identity, and possibly a list of LDAP servers.
32
![Page 33: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/33.jpg)
Interface ViewHow do the components communicate
33
![Page 34: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/34.jpg)
Interface ViewSMTP
O SMTP stands for Simple Mail Transfer Protocol. The SMTP server
handles outgoing mail.
O The SMTP server listens on well-known port number 25, POP3 listens on
port 110 and IMAP uses port 143
O Whenever you send a piece of e-mail, your e-mail client interacts with
the SMTP server to handle the sending. The SMTP server on your host
may have conversations with other SMTP servers to deliver the e-mail.
O Commands:
O HELO - introduce yourself
O EHLO - introduce yourself and request extended mode
O MAIL FROM: - specify the sender
O RCPT TO: - specify the recipient
O DATA - specify the body of the message (To, From and Subject
should be the first three lines.)
O RSET - reset
34
![Page 35: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/35.jpg)
Interface ViewPOP3
O In the simplest implementations of POP3, the server really does maintain
a collection of text files -- one for each e-mail account. When a message
arrives, the POP3 server simply appends it to the bottom of the
recipient's file.
O When you check your e-mail, your e-mail client connects to the POP3
server using port 110. The POP3 server requires an account name and a
password. Once you've logged in, the POP3 server opens your text file
and allows you to access it.
O Commands:
O PASS - enter your password
O QUIT - quit the POP3 server
O LIST - list the messages and their size
O RETR - retrieve a message, pass it a message number
O DELE - delete a message, pass it a message number
O TOP - show the top x lines of a message, pass it a message number
and the number of lines 35
![Page 36: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/36.jpg)
Technology SelectionWhy did you choose X?
36
![Page 37: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/37.jpg)
POP3 IMAP
37
O Workflow:
• Connect to server
• Retrieve all mail
• Store locally as new mail
• Delete mail from server
• Disconnect
O Advantages:
• Mail stored locally, always accessible,
even without internet connection
• Internet connection needed only for
sending and receiving mail
• Saves server storage space
• Option to leave copy of mail on server
• Consolidate multiple email accounts and
servers into one inbox
O Choose POP if…
• You want to access your mail from only
one single device
• You need constant access to your email,
regardless of internet availability
• Your server storage space is limited
O Workflow:
• Connect to server
• Fetch user requested content and cache it
locally, Process user edits
• Disconnect
O Advantages:
• Mail stored on remote server, i.e.
accessible from multiple different locations
• Internet connection needed to access mail
• Faster overview as only headers are
downloaded until content is explicitly
requested
• Mail is automatically backed up if server is
managed properly
• Saves local storage space
• Option to store mail locally
O Choose IMAP if…
• You want to access your email from
multiple different devices
• You have a reliable and constant internet
connection
• You want to receive a quick overview of
new emails or emails on the server
• Your local storage space is limited
![Page 38: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/38.jpg)
Other Views
O Data View
O Implementation View
O Deployment View
O Operational View
O Infrastructure View
You don’t have to document all the views. Pick and choose the views that are applicable to you, depending on the audience.
For instance, the Deployment team will be interested in the Deployment and Infrastructure views, while the Database Admin will be interested in the Data View.
38
![Page 39: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/39.jpg)
Design Docs
39
![Page 40: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/40.jpg)
Design Docs
O Software Architecture docs are system-level docs. They are the base of Dev docs.
Design docs are feature specific. They assume the knowledge covered in the software architecture docs and build on it. They are incremental additions to the architecture docs.
O Design docs usually accompany an architecture diagram with pointers to detailed feature specifications of smaller pieces of the design.
40
![Page 41: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/41.jpg)
Design Docs
What should a Design Doc include:
O Overview/Concept/Problem statement
O Context diagram and background information
O Possible solutions
O Analysis of possible solutions
O Solution chosen and rationale
O Areas impacted by chosen solution
O Workflow
O Code implementation
O Scenarios not addressed
O References
41
![Page 42: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/42.jpg)
Design Doc Example
O Requirement:
O User should be able to send and receive emails using Gmail.
O Background and prerequisites:
Before understanding how Gmail sends and receives email, we need to understand:
O Architecture of Gmail
O How is an email composed
O How SMTP works
O How POP3 works
42
![Page 43: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/43.jpg)
Design Doc ExampleSolution:
1. User composes an email on the client.
2. Client connects to the server.
3. Server looks up the contact database and locates the
recipient server.
4. Server transfers the email to the recipient server using
the SMTP protocol.
5. Recipient server sends a notification to the recipient
client that an email has been received.
6. Recipient client connects to the recipient server.
7. Email is transferred to the recipient client using the
POP3 protocol.
8. Recipient client downloads the email and displays it to
the user.43
![Page 44: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/44.jpg)
Design Doc Example
Solution:
44
![Page 45: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/45.jpg)
Design Doc Example
Code implementation
O <Written by Developers>
Areas of impact
O Client
O Details
O Server
O Details
Scenarios not addressed
O Sending emails to multiple users has not been addressed in this solution.
45
![Page 46: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/46.jpg)
Process
46
![Page 47: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/47.jpg)
Software Architecture Docs
O Refer to User docs, sales and support, marketing
docs
O Browse code
O Daily TOI sessions with Developers
47
![Page 48: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/48.jpg)
Design Docs
O Sprint planning
O Team discussion meeting
O Engineering requirements meeting
O Design Review meeting
O Code review
O QA TOI/Demo
O Sales and Support TOI
Add links to user docs and sales and support, and
marketing docs.
48
![Page 49: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/49.jpg)
FAQs
These docs are very technical. Shouldn’t the Developers be writing these?
If developers want to say:
Miss Piggy wants to go to lunch, so she starts a new email and types Kermit's address in the "To:" box.
They end up writing:
Assume a function AddressOf(x) which is defined as the mapping from a user x, to the RFC-822 compliant email address of that user, an ANSI string. Let us assume user A and user B, where A wants to send an email to user B. So user A initiates a new message using any (but not all) of the techniques defined elsewhere, and types AddressOf(B) in the To: editbox.
49
![Page 50: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/50.jpg)
FAQs
What are the challenges?
O Very technical
O Input to output ratio is skewed
O Need to use all skills of tech writing
What are the rewards?
O Real-time user feedback
O Sound technical knowledge – develop your own process to ramp up faster
O Niche field
50
![Page 51: Moving from User Documentation to Developer Documentation](https://reader034.fdocuments.us/reader034/viewer/2022042508/55a990551a28ab50608b45b7/html5/thumbnails/51.jpg)
FAQs
What are the skills of user documentation
that can be applicable for developer
documentation?
O Technical + Writing
O Analytical thinking
O Videos, Concept topics, Information Architecture
O Most important: Interviewing the SMEs
51