Writing Good README Docs (Benefits & How-To)

As Github repositories and accounts become more like resumes, the README for our software projects are become more important as the first impressions to prospective users and/or future employers.

That said, it is important to invest the small amount of time to make a lasting impression. The README can serve as an after-thought when we are engrossed in our code; however, it is the first thing that prospective users sees and open-source software projects are often graded on their documentation.

I would suggest approaching the README as a living document to be updated throughout the life of a project. As new features and requirements come about, then update the document periodically. Treat it as a periodic task to be completed, and it will be less of a chore.

If starting a new README, I would suggest the following:

  1. Know Your Audience – Write for your intended audience in an approachable manner without too much technical jargon. Write with detail for the technical users but also broad enough for prospective employers and/or management who may not understand the lingo of your domain, language and/or framework.
  2. Keep It Simple – I personally love lists (such as this one) so bulleted lists go a long way to illustrate your points and all they required are an asterisk before each one in markdown syntax. Shorter sentences and paragraphs make the points easier to grasp.
  3. Stay Organized – Use headings liberally in your document to organize your thoughts and convince your reader. After all, we all wish to make a point so that our read is sold on our product, i.e. our project and/or work.

Writing style is a deep and broad topic but in general, write in a voice that is comfortable to you, professional and cuts to the point. Respecting the audience by communicating effectively and efficiently goes a long way.

Some other points for writing style that I find useful are as follows:

  1. Write in Your Voice – Assume that the README is completely public since it is posted online (or may be circulated), so keep things professional but also in your own voice. Avoid slang which seems unprofessional and/or lingo/jaron which may throw off your audience.
  2. Retain Your Audience – Stay organized, hit the key points then move on. Treat the README as an email being directed to a future employer or supervisor – write professionally and to the point without belaboring the point.
  3. Have Fun – Make your points but add that hint of personality when writing in your own voice. Avoid slang but write in a tone that is informative, instructive and not too stiff.

In conclusion, the README is a public document that sets the first impression and tone for your audience and drafting/updating it is a small investment of time that can go a long way so please be sure to invest in it.

Laravel Deployment to Web Server (Outline)

Laravel applications often need their permission settings to be set when deploying to a live server for the first time.

That said, here are some steps that helped me when first deploying onto Digital Ocean:

Part 1 – Clone repo and generate new app key/.env file:

1. “git clone <github_repo_here>”

2. “composer install”

3. “php artisan key:generate”

4. Clone .env file from local source (not in repo)

Part 2 – Create/set permission folders (steps 5-8 are new):

5. “mkdir bootstrap/cache”

6. “touch bootstrap/cache/service.php”

7. “mkdir storage/framework/sessions”

8. “mkdir storage/framework/views”

9. “sudo chown -R www-data storage”

10. “sudo chown -R www-data bootstrap/cache”

Geocoding, PHPUnit/TDD & D3.js (PHP & Laravel)

Listed below are the packages/tools which I used for my CS-15 final project, which may help any readers looking to start their own Laravel apps in PHP.

Geocoding: Convert address into lat/long, useful for Google Maps, etc.

Geocoder Package: https://github.com/geocoder-php/Geocoder

Notes:

  • Install using “composer require willdurand/geocoder”
  • Documentation is useful and outlines how to work with the Geocoder class/methods
  • getLatitude & getLongitude methods return values to plug into Google Maps API, etc.

TDD: Catch errors as code base grows and becomes more complex

PHPUnit (Installed with Laravel – example tests included): https://laravel.com/docs/5.2/testing

Notes:

  • Integration tests help test by process, e.g. logging in, viewing pages, etc.
  • Changes within MVC stack may result in errors elsewhere (regression testing)
  • Ideally, tests are written concurrently with development code
  • PHPUnit output can be sparse, so options are useful
  • Verbose output: “vendor/bin/phpunit –verbose –debug –tap”

PHP Integration Testing Tutorial:

https://mattstauffer.co/blog/better-integration-testing-in-laravel-5.1-powerful-integration-tests-in-a-few-lines

Integration Testing Example:

https://github.com/walteryu/dwa15-p4/blob/master/tests/ProjectPageTest.php

Regression Testing: https://en.wikipedia.org/wiki/Regression_testing

Data Visualization & Charts: Display user data using visualization/charts

D3.js: https://d3js.org/

C3.js (Add-on): http://c3js.org/

Notes:

  • D3.js is a great tool but may require lots of time depending on chart/feature
  • C3.js provides similar functionality with a simpler API/interface
  • Basically comes down to putting data into arrays, then passing into D3/C3

D3.js & C3.js: http://stackoverflow.com/questions/31387455/loading-c3-js-into-an-html-file