2. Documentation is important
● for API users
– frontend developers
– customers using our API
– our techsupport and QA
● for API developers
– code review
– further use, development and refactoring of API
– documentation (design)-driven development
3. Perl - POD
● “Native” documentation format for Perl
● Easy to learn
● Simple to use
● Easily parseable
● Extensible (if you have fantasy)
4. How to read docs?
● perldoc
● unparsed source
● convert to HTML and read in a browser
5. How to read docs?
● perldoc
– programmers only!
● unparsed source
– programmers only!
● convert to HTML and read in a browser
– everyone
7. What is documented?
● General description
● API routes and methods
● Input parameters
● Output data
– Possible errors
8. What is documented?
● General description =head1, =head2
● API routes and methods =head3
● Input parameters =head4, =item
● Output data =head4, =item
– Possible errors
9.
10. =head3 POST /login
Loging using your credentials.
=head4 Input
=over
=item username
Username to login with.
=item password
Password to login with.
=back
=head4 Output
...
The POD
17. =head3 ANY /domain/:domain
=head4 Output
...common output...
=head3 GET /domain/:domain
=for docviewer output-from ANY /domain/:domain
=head4 Output
...specific output ...
Common output
18. Results
● DDD FTW!
– documentation is always up to date
– good programming practice
● Testing (by hand) becomes even more easy
● No need to write an admin panel
– people use API console instead