Source Code Documentation

Generating Documentation Using PHPDocumentor 2

I though I would write a little bit about how we document our source code at Chic Computer Consultants and give an example of how we setup our documentation website.

As we all know it is important to have up to date documents and we try to keep our as up to date as possible.

Inline Documentation

We use inline comments inside our source files to document our source code we use Phpdocumentor to generate a documentation website from these inline comments.

It is very simple and makes life a lot easier by automating the updating of our documents allowing us to just run it by cron and that is all we have to worry about.

You can add inline docs simply by using the following comments in you source files,

/**
* Comment Header
* <p>Some stuff here to describe our content</p>
* @package default
* @category core
*/

The above comment contains a paragraph and also defines the package directive this directive is used with @category to compartmentalise your source tree.

/** Another PHPDocumentor comment */

Above is a simple comment with no directives for a complete list of directives please see this page and for more information on using Phpdocumentor please see here.

Generating Documents

To generate the documentation we use PHPDocumentor 2 to transverse our source tree and parse the inline comments into a nice easy to use format which is web accessible for our web site we use digest authentication to restrict access to our documents.

Our first task was to install PHPDocumentor which is really simple to do as they use pear to package up their software.

root@chic:~# pear channel-discover pear.phpdoc.org

root@chic:~# pear install phpdoc/phpDocumentor-alpha

It should now be installed on your system under /usr/bin which should be in your $PATH allowing you to access the program by typing phpdoc at a shell prompt.

Once we had installed the software needed to generate our documentation we needed to modify the configuration file so we can change the title and heading to something more custom.

Vi Config

The file we need is the main configuration file for Phpdocumentor you could also create a custom one but the default suited our needs. There is more information in the docs here. So our next step is to use the following command,

root@chic:~# updatedb && locate phpdoc.tpl.xml

This command will update the slocate database then us slocate to try and find the config file but only if the previous command was successful. The file is named phpdoc.tpl.xml and on our system (Debian) it was located here,

/usr/share/php/phpDocumentor/data/phpdoc.tpl.xml

If you open up this file you can add a custom title which in our case we named it Chic Computer Consultants Documentation. You can use any editor we like vi or nano.

vi /usr/share/php/phpDocumentor/data/phpdoc.tpl.xml

Once in vi switch from command mode by pressing i and add the following line to the bottom of the file inside the <phpdocumentor> tags (file is an XML file) then exit vi saving the file (shift zz).

<title>Chic Computer Consultants Documentation</title>

After this we needed to setup a virtual host on Apache, configure the DNS to point towards our documentation website (docs.chic.uk.net) and install dependencies (this may vary on your system).

apt-get install php5-xsl graphviz graphviz-dev

Then finally we can generated the documentation we decided to use the default template which is responsive*.

phpdoc -d /path/to/web/root/source_tree/ -t /path/to/web/root/docs/

Once the program finishes running our documentation website has been created so its time to check it all worked and looks good.

We use cron to update our documentation every night but you need to add the -q switch to the end of the above command this will suppress any output.

Documentation Example

More Documents

We also have other types of documents to help us develop our software, we use Dia for creating diagrams of our database schema. We use a relational database (RDBMS) so we map our associations using it. You can also create other kinds of diagrams using Dia but that is beyond this article.

For our UML documents we like to use umbrello which we think is great for modelling our class hierarchy and creating class maps helping us keep track of whats doing what.

UML Diagram

For any word processor documents or spreadsheets we use Libra Office which is a fork of OO.org. We use a word processor sometimes when we need to document use cases and such things.

Conclusion

We hope this article gives you an idea of how we handle documenting our development and some of the tools we use to accomplish this.

As you can see from our list of documentation software all our needs are provided by free and/or open source software stacks. Basing our development entirely on an open stack suits us as a company.

On a side note progress on the care related news system is coming along well and we are currently integrating it into our social media accounts so we will be documenting this system in a future article.

We have implemented so far, the administration panel, news editor panel and the news article front end so it should not be long before we are providing news.

We would also like to get some news syndication if we can find any one interested in providing and/or using our service.

Appendix

* At the time of writing 2013-05-29

Cross Browser Testing Sessions

The Joys of Web Standards

While developing our new templates we had to make sure that our markup is displayed in the correct way across multiple browsers, operating systems, screen sizes and screen resolutions.

Our company likes to support and use open web standards because they make sense and you know if a browser implements a said standard it will display the same regardless of the user agents platform (life is never that easy).

Standards

Testing on all these devices can be quite a task which normally involves some kludging and compromises in terms of layout and style as all rendering engines interpret markup differently or maybe they do not support it at all.

Testing Platforms

The requirements for testing can lead to needing quite an extensive testing platform so for our needs we used Mint Linux 13 (Maya), Ubuntu 13.04, Windows XP SP3, Windows 7 SP1 for PC. We could not test on a Windows 8 rig because we do not have a license for it currently but when we pick one up we will run our use cases on it.

Besides these operating system we decided to also run a bunch of use cases on some Android™ 4.1.2 and 4.0.3 devices and iOS 6.1.3 (iPhone and iPod) to make sure it displays correctly on handhelds using the default style sheets.

Droid

Our handheld devices were a Galaxy s3, HTC Sensation, Nexus 7, iPad 2nd generation, iPhone5 and a iPod 4th generation.

We run our operating systems on separate devices and also multi boot setups but you could use a virtual machine to run all these separate operating systems but that is beyond the scope of this article.

Web Browsers

Another consideration of ours was to compile a list of popular browsers and decide which we are going to use for testing. The obvious ones are Firefox (geko), Chrome (webkit), IE (trident) and Safari (webkit).

Once we had the list of browsers complied we had to decide which platform(s) to install the browser on and also which version of the browser to install.

Mozilla

We like to keep all the old Windows browsers on XP and more recent browser versions on Windows 7 it make more sense to use older ones on the older OS.

Also we sometimes use a program called IETester which allows you to use all IE rendering engines since IE5.5 up to IE10. This application is great for doing all your testing in one place and can make life a bit easier.

Chrome

You can also put Internet explorer into quirks mode using the button by the address bar this will make IE use the quirks rendering engine which can help with old web sites but I personally tend to use IETester.

So in the end our browser versions and platforms were,

Mint 13 (Maya)

• Chromium 25.0.1364.160
• Firefox 21.0

Ubuntu 13.04

• Chromium
• Firefox 20.0

Windows XP SP3

• Chrome 26.0.1410.64m
• Firefox 2.0.0.11
• Internet Explorer 7 and 8 (IETester)
• Safari 5.1.7

Windows 7

• Firefox 20.0.1
• Chrome 26.0.1410.64m
• Internet Explorer 9 and 10 (IETester)

Screen and Resolutions

The minimum screen size we are targeting is 15" @ 1024x768 so we used an old Phillips Syncmaster I had laying around to make sure the website was displayed correctly. We also used a 19" @ 1440x900 Asus monitor to see how it renders on a larger screen. Both displayed the website correctly and as expected.

Monitors

Connections and Bandwidth

You might have noticed I have not mentioned anything about bandwidth which used to be a consideration and may still be for some countries but looking at the avarage speed of UK broadband which is 12.7Mbit/s^[1], this is high enough for us not to worry about file sizes to much.

Although we always try to keep size down and latency up for our web pages and servers, always trying to follow the KISS mantra.

Use Cases

Next up we dusted of our use cases which we do with every browser to try and test all of our different templates and follow common actions of our visitors

One use case is for viewing a care homes basic listing so we open up a browser tab and request the index page of our website. From there the next step is to click the care homes link in the header which takes us to the UK country page.

This is a list of links to UK county pages from here we select a county (Hertfordshire) and click on it which takes us to the town page.

On the town page is a list of links to towns in the county so we click on Watford which takes us to the town page which is were the information for each home in the town is listed.

From here you can click on the more info links to get the basic listing which we consider a sort of home page for the home on our site.

Below is a video of the use case in action it was a screen capture using VLC to record the stream using an OGGVorbis codec*.

Problems Encountered

Finally we will cover some of the problems we encountered which were surprisingly few considering the task at hand.

Our first task we had to implement a custom style sheet for IE 7 because it was shifting the right set of links in the header down to a new line.

We use a browser conditional <!--[if IE 7]> which means all other browsers apart from IE 7 will ignore this because they will think its a comment but IE being IE it will use the style sheet.

This allowed us to make the navigation links 24% in width rather than 25% I am not certain on what has caused this but removing padding and margins made it work in IE but that was unacceptable in terms of style so we decided to make the widths small.

I would guess that IE 7 uses a different box model than the rest and it also does not support the box-sizing CSS property either.

This was our only main problem and involved a bit of a kludge to fix but we are happy with the results so far.

We do have some outstanding enhancements for adding authorship microdata, adding language and dir attributes to our <html> tags and a couple of small things.

Also the website displays terribly in IE 6 but we do not wish to support such and old browser I would also assume they were on an old machine with and old monitor so the website would not look great anyway.

IE6

Thoughts

We are happy with our testing and the new templates passed all our use cases once the custom IE 7 style sheets were implemented.

Our pages conform to standard** and our web site displays the same across all our target platforms, browsers and devices which is exactly what we want.

The Care Homes Directory will be releasing a news system so we can publish care related news topics direct on our website.

I will be writing an article about it in the coming week about how we integrated into various social media API so when we publish it gets maximum exposure.

We hope to be releasing within the next few weeks after the QA has been done and any remaining features are implemented.

Appendix

[1] http://stakeholders.ofcom.org.uk/market-data-research/other/telecoms-research/broadband-speeds/infrastructure-report-2012/ (originally accessed on 2013-05-18)

* I think this blog software has mangled the video as it was 1080p @ 30fps but looks awful now in full screen.
** Apart from enhanced listings due to CKEditor using non standard markup.

Development Platforms and Practices

3C Web Development

In this article we will be covering the development environment and platforms that Chic Computer Consultants use while developing The Care Homes Directory website. We will cover what tools we use and the reasoning behind our choices.

Platforms

When we begun developing The Care Homes Directory we decided upon using the LAMP stack as our server platform. Our web server is a quad core, 4GB RAM, SSD machine running Debian 7.0 (Wheezy x86_64) and Apache 2, MySQL 5 and PHP 5 sitting on top.

This platform has been very stable for us and we currently have a good amount of unused resources. While monitoring a server you can use the utility top to get the load average for the machine giving you an idea of how busy the machine is (or cat /proc/loadavg).

GNU/Linux

We have heavily customised our server changing the default scheduler to use a deadline rather than cfq. We also configured our TCP stack and installed PHP accelerators. We decided to use XCache for PHP optcode caching.

As well as these changes we modified the MySQL, PHP and Apache configuration to provide a faster install. On top of all this we did the usual hardening and configuration of a GNU/Linux system you would expect.

Bugzilla Bug Tracking

Even the best software has defects so obviously when developing you need to have a system for tracking bugs we use Mozilla's Bugzilla for our bug tracking.

We can raise any defects and/or enhancements to our code base directly from a web browser which is great for our testing team.

Mozilla's Bugzilla

Before we release any software it must go through regression testing using unit tests and also any other use cases which need to be tested for before being sent for Q&A and general release.

We try to follow a rolling release schedule and use agile development to produce incremental updates to our code hence why rolling releases suit us.

Subversion Version Control

For source code revision control we decided to use Subversion rather than CVS or git which were the other two candidates we chose (we were already using Subversion when git was released). Subversion fits all our use cases and we have found it easy to use.

We have a main repository which allows all developers to access our source code and work independently of each other and when any changes have passed Q&A then it is merged into the trunk and tagged as a stable release.

To help add security (adding layers is good) when providing remote access we run everything over SSH tunnels including sftp so for accessing our repositories we require svn+ssh be used.

Subversion

We did not go with CVS due to problems with it handling binary files and some people would consider it a bit "over the hill" and should be superseded by Subversion. Although we have do have previous work experience with CVS which went in its favour.

Recently we reviewed our choices and had a look at what git has to offer but we decided to stick with subversion as it has worked perfectly for us so "if it aint broke dont fix it", although git's distributed nature is appealing to us for the obvious replication advantages.

Developer Workstations

Our developer workstations run Mint GNU/Linux which is a derivative of Ubuntu which is another OS we allow on our workstations. We do use other operating systems inside the company but we are mainly a GNU/Linux house. The other OS we use are Windows, Android and iOS.

We do not use any IDE for our web development as we find gedit and Filezilla a good combination for any PHP, Python or working on writing markup. We do use Eclipse when developing in Java but that is beyond the scope of this article.

Mint & Cinnamon

In regards to our testing environment this will be covered in another article which will follow the release of this document. Selenium is a great tool for browser automation and we have test units which make use of it. We also make use of other tools but again this is for a future article.

Conclusion

I hope you have enjoyed this article and it has given you an insight of our development environment and how we like to approach things.

We will be writing another blog post about how we tested porting our site to HTML 5 and CSS3, the cross browser support issues we encountered and a little bit about our methods for testing our software.

Please take a moment to visit our Facebook page.

Microdata and Breadcrumbs

New Vocabulary

When we moved our website over to HTML 5 it allowed us to start using microdata to markup our information and try to aid search engines and screen readers make sense of the data on our site.

First we chose a vocabulary to use, the vocabulary defines the way we describe our data and what it all means, in the end we decided on using schema.org.

Marking up

Once we had decided what vocabulary to use we then added the itemscope webpage to our template body tag to allow us to define anything inside the <body></body> tags as a property of WebPage. The schema for WebPage is a child of CreativeWork which is in turn a child of Thing.

Then we added some microdata to our town page which is a listing of care and nursing homes in the selected town. We set the listings scope to LocalBusiness which describes "A particular physical business or branch of an organization"^[1] and is ideal for our use. We could extend this but we will discuss this later.

Town Listing Markup

LocalBusiness has certain properties which are used to describe attributes think of it like OOP (Object Orientated Programming) where you have objects and those objects have attributes such as a Person object that could have attributes eye colour, hair colour etc..

Our town page has information about each listing and the associated itemprop such as the homes name, address, telephone, fax, geographical coordinates (meta data), url and description.

By using the itemprop attribute we can help describe exactly what each bit of text means in our webpages.

Leaving a Trail

Next we added some breadcrumbs to the site templates main navigation sections which are inside HTML 5 <nav> tags. Breadcrumbs can be used to help define the hierarchy of your site and can also be used by search engines. The screen shot below show a Google SERP which is displaying some breadcrumbs for the search keywords "microdata breadcrumb"^[2].

Breadcrumb Link Trail

Our site makes use of the title and url properties and we hope implementing breadcrumbs will aid any robots crawling our website and also allow our users to access the pages hierarchical links. Here is some further reading on breadcrumbs.

Breadcrumbs Inside Nav Tags

Extending Vocabulary

We are considering extending the vocabulary for LocalBuisness to make our data even more granular the parent child relationship between schemas could be used to create a CareHome schema which could extend the LocalBuisness schema.

Currently we feel it would be beyond our websites scope to start providing custom schemas although it has been added to our possible feature list and will be considered at a later date.

Listing Microdata

Conclusion

We hope this article has given you a better understanding of microdata and how The Care Homes Directory has integrated this technology into our website templates.

As always we will be reviewing our microdata and also cleaning up the current tags we have, as there is always room for improvement. We are also considering adding more item properties to our site.

Please check back soon because we will be writing some more articles and hope you find them useful. We will be producing a guide to using The Care Homes Directory Enhanced Listings on our site soon and an article on our development platform and development practises.

You can also contact me using my Google Plus account name, Chris Elsen.

Appendix

[1] http://schema.org/LocalBusiness
[2] SERP results (originally accessed on 2013-05-09)

Care Homes Directory New Feature Release

Care Homes New Features

We have been working hard on adding some new features to The Care Homes Directory and now have a new look for our basic and enhanced listing pages.

Adding a tabular navigation bar for the listing provides links to local amenities, Neighbourhood view, Street map and a form for contacting the home.

Enhanced and basic listings are pages which contain information on each home so they can be thought of as a sort of home page.

Main Page

The main page is the landing page for enhanced and basic listings and is were visitors are directed when viewing a listing from our town page. For enhanced listing we also display an overview of the home written by the contact point of the home. This allows full control of any descriptions of the service.

Details Page

Local Amenities Page

Our local amenities page is a list of local places within a few miles of the home so you can now see what kind of businesses and services are available near the home, for a full list of services please see the bottom of this post.

I have highlighted the local amenities with a red border in the screen shot below to give you an idea of how it all looks.

Amenities Page

Neighbourhood Page

We also now have a tab for the Neighbourhood page which is a street view of the homes local area allowing visitors to see the surrounding area and what it may look like.

Neighbourhood Page

Map Page

The Map page is a road map of the local area it provides some controls for viewing more homes in the area.

If you zoom the map out it will populate the map with pins of other homes near by. This also works if you scroll the map using your mouse and clicking and holding the left mouse button.

Map Page

Contact Page

The final tab is the contact page for the home, if we do not have a current email address associated with the homes contact point then no form is displayed. Enhanced listings allow home owners to have potential clients contact them directly from their listing page as a current email address for the home is required during signup.

Contact Page

Conclusion

The Care Homes Directory hopes these new features will be helpful to our site visitors when looking for a care provider. We also hope they provide some useful tools to home owners and managers to control their homes information and attract more potential clients.

Enhanced and Basic Listings

Please review some of the homes taking advantage of the new features we have provided,

• Minchenden Lodge (Enhanced Listing)
• April Park Nursing Home (Enhanced Listing)
• Farmhouse Rest Home (Enhanced Listing)
• Alexandra Park Home (Basic Listing)
• 1 Old Station Close (Basic Listing)

Local Amenities List

• bank
• beauty
• salon
• bus
• station
• cafe
• church
• dentist
• doctor
• florist
• hair care
• hindu temple
• hospital
• library
• mosque
• movie theater
• museum
• park
• pharmacy
• physiotherapist
• place of worship
• post office
• restaurant
• shopping mall
• subway station
• taxi stand
• train station
• veterinary care
• zoo

Moving Forward With HTML 5 and CSS3

Porting Templates

We have now moved our website templates over to HTML 5 and CSS level 3 also switching to a tabless design using inline blocks, divs and unordered lists for navigational links. It is a kind of hybrid design between a fixed width website and an elastic layout.

Index

The site was originally designed in early 2000 and was in need of a new overhaul. It had been overhauled once before from HTML 4 to XHTML but apart from this it has mainly stayed the same. I always like to think content is king and layout is queen.

Main site navigation in the header and footer are now unordered lists (<ul>) which are displayed inline making them horizontal. The left navigation bar uses the same approach but is a vertical list of links with text-align set to right.

Using the border-radius property allows us to round the corners for our header and footer blocks. Rounded borders look more appealing than square.

Our site now uses emphasis (em) for defining the font size of text this allows us to scale up/down the text size if the user has a browser zoom level other than 100%. The font family we use is Verdana, Arial, Helvetica, sans-serif these are considered web safe and are my preferred style.

Markup

One of the first tasks we had was defining a minimum screen resolution of which to support in the end we decided that 1024x768 would suffice according to this webpage only 13% have this resolution (January 2012) and 1% used 800x600.

Using the CSS properties for min-width and max-width we can set the size in pixels of the wrapper div for us this is 1280px. By giving it a width in pixels it stops the site layout crunching up when the browser window is minimised. We are in the process of making all our borders and margins use emphasis (em) instead of pixels.

We did encounter some problems with internet explorer 7 which is the lowest version we have decided to support. We had to create a separate CSS file for IE7 to fix a problem with the header link widths. In IE7 these are set to 24% and all other browsers it is 25%.

The website still displays in lower versions but it does not look as good. Other major browsers display the website correctly as they tend to follow standards a bit better.

Padding was another problem which was encountered due to the box model adding it and any margins to the outside of a container which can cause overflow. I learnt a little trick to make it add any padding and/or margins to the inside of the box. You need to use the CSS box-sizing property and give it the value border-box.

Although HTML 5 has yet to be ratified and is still in the draft stage we feel it is sufficiently complete for our use. We also feel that aiming to use more recent web technology will help future proof our website.

Over time we will be implementing a style sheet specifically for mobile devices by using the media attribute of the link tag. We will also be modifying the template using the CSS display property to make the right column merge into the centre column.

We will be writing a future article focusing on implementing the mobile style sheet and on testing our new site design and the cross browser nightmare that can ensue. Finally please take a moment to visit our site.

Welcome

Web Development

Welcome to my web development blog where I will chronicle and discuss the development of our website The Care Homes Directory which is one of the leading websites in the UK for senior care information.

The Care Home Directory is a website which provides information on UK care and nursing homes which includes care and nursing agencies. You can visit the website here.

We will be providing information about the website, its features and the technology used to develop it in future posts I hope you enjoy following our progress.