Documentation and Deployment

Transcription

1 Documentation and Deployment CS 370 SE Practicum, Cengiz Günay (Some slides courtesy of Eugene Agichtein and the Internets) I know what I learned this semester: CS 370, Günay (Emory) Documentation and Deployment Spring / 19

2 Agenda Upcoming milestones: 4/22: Hacking ends; submit survey reports on GitHub by midnight 4/24: The APPrentice! Make sure everything is integrated for your final demo, or you may be fired! 5/5: Final deliverables: installation instructions, user documentation, code documentation, package CS 370, Günay (Emory) Documentation and Deployment Spring / 19

3 Agenda Upcoming milestones: 4/22: Hacking ends; submit survey reports on GitHub by midnight 4/24: The APPrentice! Make sure everything is integrated for your final demo, or you may be fired! 5/5: Final deliverables: installation instructions, user documentation, code documentation, package Today s episode: What did we learn this semester? Down the memory lane. CS 370, Günay (Emory) Documentation and Deployment Spring / 19

4 Agenda Upcoming milestones: 4/22: Hacking ends; submit survey reports on GitHub by midnight 4/24: The APPrentice! Make sure everything is integrated for your final demo, or you may be fired! 5/5: Final deliverables: installation instructions, user documentation, code documentation, package Today s episode: What did we learn this semester? Down the memory lane. Yeah, but we re not done yet. Let s learn how to release code. CS 370, Günay (Emory) Documentation and Deployment Spring / 19

5 Note about survey reports due tonight Survey reports must contain: Collection of all answers you collected Summary information What s the summary? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

6 Note about survey reports due tonight Survey reports must contain: Collection of all answers you collected Summary information What s the summary? Examples: Number of participants Demographics of participants Percent that liked your app Most requested feature or most disruptive bug Average ranking or other numerical summaries CS 370, Günay (Emory) Documentation and Deployment Spring / 19

7

8 Entry/Exit Surveys Exit survey: Security, Market and Competitive Analysis In public-private key authentication, explain why we need a certificate authority. Is a great idea sufficient to get venture capital funding without doing market analysis? How do you compete with other products? What should be your strategy? Entry survey: Documentation and Deployment What was your most annoying experience installing a program without instructions? Do you use automatically-generated code documentation? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

9 Releasing code on GitHub CS 370, Günay (Emory) Documentation and Deployment Spring / 19

10 Releasing code on GitHub CS 370, Günay (Emory) Documentation and Deployment Spring / 19

11 Headhunters look into your GitHub accounts GitHub is your resume? More critical view on hiring indicators GitHub account profile for job seekers You should seriously consider making your repos public. Let me know. CS 370, Günay (Emory) Documentation and Deployment Spring / 19

12 Your code looks better with documentation

13 Your code looks better with documentation And looks worse without documentation So how to go around for adding docs?

14 Principles of code documentation Write self-documenting code: Use meaningful function, variable, file names Informative sanity checks and error messages CS 370, Günay (Emory) Documentation and Deployment Spring / 19

15 Principles of code documentation Write self-documenting code: Use meaningful function, variable, file names Informative sanity checks and error messages What to avoid? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

16 Principles of code documentation Write self-documenting code: Use meaningful function, variable, file names Informative sanity checks and error messages What to avoid? Excessive documentation Unecessary documentation: repeating what to code says What s the problem? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

17 Principles of code documentation Write self-documenting code: Use meaningful function, variable, file names Informative sanity checks and error messages What to avoid? Excessive documentation Unecessary documentation: repeating what to code says What s the problem? Run the risk of being inconsistent with code CS 370, Günay (Emory) Documentation and Deployment Spring / 19

18 Code documentation example So what s the best way? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

19 Code documentation example So what s the best way? Always put documentation for functions and their input-ouput parameters Preferable in standard format, so browsable documentation is generated automatically (doxygen, phpdoc, javadoc,... ) Add comments into critical parts of code Explain why, not how. CS 370, Günay (Emory) Documentation and Deployment Spring / 19

20 Code documentation example So what s the best way? Always put documentation for functions and their input-ouput parameters Preferable in standard format, so browsable documentation is generated automatically (doxygen, phpdoc, javadoc,... ) Add comments into critical parts of code Explain why, not how. Which one is more useful? OR /** This function adds two numbers by using the addition operator * and then returns the result. */ /** This function sums its inputs before we can use it as a * multiplier in the measurement */ CS 370, Günay (Emory) Documentation and Deployment Spring / 19

21 A note about style Who cares about code style? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

22 A note about style Who cares about code style? Gets you mad when working in a team? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

23 A note about style Who cares about code style? Gets you mad when working in a team? Keep it consistent: Function, variable, file naming conventions Naming special constructs for your project (e.g., views, controllers) Spacing and parens: make sure everybody s comfortable with the style Documentation: make sure autogen doc looks right! CS 370, Günay (Emory) Documentation and Deployment Spring / 19

24 Time for deployment...

25 Deployment and tools Deployed anything before? What s involved? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

26 Deployment and tools Deployed anything before? What s involved? Packaging Installing web services, domain names Providing installation instructions User documentation CS 370, Günay (Emory) Documentation and Deployment Spring / 19

27 Deployment and tools Deployed anything before? What s involved? Packaging Installing web services, domain names Providing installation instructions User documentation Do you use any tools? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

28 Deployment and tools Deployed anything before? What s involved? Packaging Installing web services, domain names Providing installation instructions User documentation Do you use any tools? Makefile for all Ant for Java Phing for PHP IDEs: Eclipse, NetBeans,... Others? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

29 User documentation: installation instructions Terrible installation instructions anyone? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

30 User documentation: installation instructions Terrible installation instructions anyone? Don t do it! Include: Brief description of software (in case it s not suited for purpose) Requirements (software, hardware, knowledge,... ) Compilation and installation steps Troubleshooting Contact info CS 370, Günay (Emory) Documentation and Deployment Spring / 19

31 User documentation: usage instructions Help! CS 370, Günay (Emory) Documentation and Deployment Spring / 19

32 User documentation: usage instructions Help! In-program help is the best Sometimes you need a nice manual Mostly a README or a few Wiki pages would be sufficient CS 370, Günay (Emory) Documentation and Deployment Spring / 19

33 User documentation: usage instructions Help! In-program help is the best Sometimes you need a nice manual Mostly a README or a few Wiki pages would be sufficient You are required to submit: installation instructions usage instaructions code documentation properly packaged (Android APK, JAR/ZIP file, etc) CS 370, Günay (Emory) Documentation and Deployment Spring / 19

34 What did I learn this semester? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

35 What did I learn this semester? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

36 But most importantly... CS 370, Günay (Emory) Documentation and Deployment Spring / 19

37 But most importantly... CS 370, Günay (Emory) Documentation and Deployment Spring / 19

38 We did what? Seriously now... CS 370, Günay (Emory) Documentation and Deployment Spring / 19

39 Seriously now... We did what? 1 Python: Django 2 Webapps: HTML, HTTP, CGI, Javascript, AJAX, SOAP, WATER 3 Mobile: responsive vs. native 4 Entrepreneurship: startups, business side, legal, marketing, competition 5 Agile software development: scrums, user stories, rapid development iterations 6 Security: hacking, authentication, phishing CS 370, Günay (Emory) Documentation and Deployment Spring / 19

40 Seriously now... We did what? 1 Python: Django 2 Webapps: HTML, HTTP, CGI, Javascript, AJAX, SOAP, WATER 3 Mobile: responsive vs. native 4 Entrepreneurship: startups, business side, legal, marketing, competition 5 Agile software development: scrums, user stories, rapid development iterations 6 Security: hacking, authentication, phishing And you did? CS 370, Günay (Emory) Documentation and Deployment Spring / 19

41 Seriously now... We did what? 1 Python: Django 2 Webapps: HTML, HTTP, CGI, Javascript, AJAX, SOAP, WATER 3 Mobile: responsive vs. native 4 Entrepreneurship: startups, business side, legal, marketing, competition 5 Agile software development: scrums, user stories, rapid development iterations 6 Security: hacking, authentication, phishing And you did? 1 Programming 2 Presentations 3 Testing 4 Reporting bugs 5 Documentation CS 370, Günay (Emory) Documentation and Deployment Spring / 19

42 Upcoming episode is the finale APPrentice! Be very afraid! Evaluations now! CS 370, Günay (Emory) Documentation and Deployment Spring / 19