The Devils in the Documentation....not quite but its a start!

So being a software engineer I find myself getting frustrated with the lack of emphasis put on maintaining light weight documentation. Now don’t get me wrong heavy weight documents outlining every single intricate detail of a piece of software is not only a waste of time to the person writing it but also a waste of time for the person reading it. When you start working on a piece of software, particularly something new to you, you need a few things to get you going and point you in the right direction. 

One is the existing code base, ideally nicely written and self documenting with meaningful class names, method names etc and a little magic which isn't avoidable. Another must if you are going to be working on a meaningful/sizeable feature is a basic overview of the system, its interactions basic concepts. Not only do you get a feel for how things currently work, you get a feel for how they fit together, how you can add value, how they may interact with other systems. You get a snapshot of naming conventions and vocabulary which hopefully should be mimicked in the code base. There is a useful tool call code-words for extracting out word clouds used within a code base, run it against a code base you are working on and see what you find, it may be interesting. Combine these things together and getting up and running on a new project or new feature is much easier in my opinion. I don’t even have a preferred type of document of diagram, sequence diagrams, UML heavy weights, simple process flow diagrams, these all can bring value and are better than nothing. Obviously the caveat is that you need to ensure you include the time needed to update these bits of documents and diagrams as you add value and change systems over time otherwise they get out of date and tell a different story than what is really happening. Diagrams in my opinion are much easier to update, easier to maintain and much more fun and enjoyable to work with. They don't always show you the fine grain details which you need, in my opinion these are found in the code base and possibly in more focused diagrams looking at particular interactions or solutions.

I think the real point here is that the documentation of a system needs to be treated with respect just as the code, the tests, the infrastructure and the business itself should be. The devil is always in the detail and the details are going to be in the code base or peoples head, the documentation will give you means to pin point where to find the details and hopefully not make assumptions which turn out to be unfounded. 


I feel that this relates to all software engineering I have done, open source, personal and at an enterprise level. This post is purely a complete rant after hitting several issues to do with the lack of knowledge or information when working on projects professional and in my spare time....rant over! Basically stop being lazy and give me a simple digram!!


James Morgan

Cinnamon Applet Development

Having been back from travelling and before strting my new job I've had some from time. Over the last week I have been playing around and looking into improving an old project which is an Cinnamon Applet which interacts with GitHub's API and displays details on a persons public repositories. Written in JavaScript and utilizing any underlining Cinnamon code via GObjectIntrospection its reasonably pleasant to work with, given a nice editor such as gedit with a few plug-ins. I do have a few gripes with Cinnamon Applet development but I will get to this later in the post.

The applet is can be installed via the new applet management console in Cinnamon 1.8 which now displays published applets from the Cinnamon website as well as installation and configuration. Along with other improvements Cinnamon 1.8 now has a fully baked in Settings API which means that developers like me don't have to have a home brew solution to this issues, previously I was using GTK Glade and some custom JavaScript code to control this, the addition of the Settings API makes it a much easier and hassle free even if its not got all the features I wanted.

The Applet has improved after a few rounds of re-factoring plus the additions of a few features such as correctly using the HTTP headers and hopefully not exceeding your free public API limit which did happen occasionally. I have also added change notifications which means that if the number of issues, forks and watchers changes for each repository then I pop a notification to the user about the change with a link to the repository, its basic but can be useful, I plan to improve/expand on this in a future release.

Next on my list of things to do is to give the option for users to use GitHub 0Auth Token authentication and to increase the complexity of the plug-in. I would like to give users more options for what they see and use in the applet, expanding the controls. Its nice to learn new things especially something community driven like Linux Mint development. Having used Linux Mint for 18 months solid as my main desktop and development environment I feel it was a wise move and one I don't regret. I use Windows 7 and Ubuntu in my day to day job as a Software Engineer and they don’t feel as nice to work with and don’t give me what I want from a desktop experience. I believe Cinnamon and Linux Mint have a good future and look forward to seeing whats new. N.B. Cinnamon 2.0 has just been released.

The application can be seen in more detail on the Cinnamon website and all code and further information can be found in the GitHub repository. Let me know what you think.

Gripes and Grimes

Settings API

The Settings API is nice to work with and even has some good documentation and a few example can be found online which is good. I would how ever like more controls available for what options would be displayed. For example in a normal configuration option I would tend to put links to various websites, display version numbers and also have small blocks of text highlight things and or simple displaying help etc. 

Documentation

This is just a general wine about the state of documentation for Seed and GJS, I know there are sites available such as this but when you have never done things before it would be nice to have an example of how to interact with the API's and how to overcome some basic coding problems. On a good note the Linux Mint development time are always on IRC and always try to help if they can.

Unit Testing
Coming from a Java background and writing unit tests and aiming to be test driven at work everyday I find it hard writing code without tests. In essence what happens when combined with the lack of documentation is, I write some code which I don’t know even compiles, install it, restart Cinnamon and see what happens. On several occasions I have got myself into issues and even and to restart my machine. Maybe there is a better way to develop these applets and extensions but I'm not sure what that is, there certainly isn’t first class support for it yet.


I know that in reality since its all Open Source I should really try fixing the grips I have raised., maybe this will be next on my list of projects.

Back to the Land of Nod...

Having landed from our 6 month travelling trip around SE Asia and a bum numbing 36 hour journey including a truck, boat, bus, three flights and a car journey I have arrived back in the U.K. Amongst other things I have a long and extensive list of jobs, projects and tasks needing to be done to get back into the world of Software Engineering and computing.

I have a few ideas of various applications both web and mobile based which are related to travelling and which I will investigate the feasibility of, technology and any possible existing apps, maybe only writing them down in some detail whilst they are fresh so when time permits I can attempt to make them. I have a Linux Cinnamon plug-in which hasn’t been working for nearly 3 months since GitHub changed their restful based API and I have been unable to change code and commit any fixes whilst being away, some users reporting issues and it looks like popularity had dropped because of it. I plan on refreshing my Linux Mint install with the latest version and generally cleaning up my PC which before I went again always seemed to be last on the list of things to do on a weekend for obvious reasons. I have literally thousands of emails from various mailing lists I am members of which to be honest I will most likely just clear out and start again, picking up with the latest chatter and developments from now. Of the probably 5000+ emails I reckon only about 100 are relevant which relate to things I need to follow up on check and take some action, many off which are job related which before I went away I paid little attention to, oh how this has changed! Obviously I need to start thinking about jobs and where to work, what to do and where to live, updating my CV (Resume Link) and LinkedIn profile.

I have travelling related jobs as well as well including sorting out the thousands of photos I have form the trip, selecting some to show friends and family since I don’t think they can endure spending an entire day looking though so many. I have washing and other clean up jobs to do from the trip. I have a few blogs to post from the travelling along with getting used to British weather and generally just getting used to be in the U.K.

Not only has travelling been eye opening and truly the most enjoyable thing I have ever done it also allows you to completely disconnect yourself and clear your mind, not being connectable by phone, text or Skype (unless you want to), not having a PC or laptop and just having a small phone to check your emails and write the blog (occasionally), not having to perform your daily routines and chores has be highly enjoyable and free. I hope to take from it so much but also just a fresh and clean start not only in body but in mind and perspective on things from work, life, family, friends and everything else that they entail and mean to me. Technology and engineering was a passion of mine before I left and I don’t plan to change this, maybe the way I code will change, maybe not, hopefully the way I interact with people will change, maybe challenges will seem smaller?

I have work to do...

James

Hacking from a phone, not the easiest

Recently I've had two people fork and contribute to an open source project I created to add GitHub integration to Linux Mint, inparticularly cinnamon the replacement window manger. Not only was it great to find some people actually using my app but I also really appreciated GitHub for its social and open nature. Using it in a closed cooperate environment does work but when you sit next to the people who are working on the same code its always best to speak to someone in person as opposed to simply commenting. However this isn't always possible and GitHub provides a good medium for this. Both contributions came from forks woth pull requests which allowed for good two way communication and code reviews etc. The problem I did have is that as I'm travelling I have no access to my linux mint install, my GitHub, development and testing tools so it had to be checked, merged and released from my phone, it took a very long time! Hacking from my phone was hardly hacking as the toolset available to me a text editor, zip/unzip application, browser and GitHub app (which has limited functionality). I managed to check the code on the pull request, do some reading, merge it in to master and when it came to a release I downloaded and extracted the zip of the main repo, copied some files to a new folder, tweaked some text and zipped it back up. I also sent it to one of the contributors for a quick test. I can upload the zip with the browser and hopefully a new version will be out and have some new features and bug fixes. Not bad from a phone I reckon!

James

Embarking on a big one!

Approximately 4 weeks before we embark on one hell of a big adventure with +Isobel Perrin my mind is starting to wonder, what the hell am I going to do if I cant write any code for 6 months! I mean....no code, no IDE, no Java, no JavaScript, no AngularJS, no morning standup, no banter with the team, no late night hacking, no diagrams, no mailing lists....the list goes on....it's going to be a challenge!

Hopefully this will soon subside and with my newly created account on Cloud9 hopefully this will hit the spot with any crazy urges to hack away, not entirely sure how well it will work on a nexus 7 though?

The intended itinerary is as follows:

1. China
2. Vietnam
3. Cambodia
4. Laos
5. Thailand
6. Indonesia
7. Malaysia
8. May be somewhere in Europe before we had back to reality

Being nearly a year from birth to actual reality and having privately spoke about it for years I have mixed feelings about leaving work, dropping my routine, not having regular contact with some great friends and colleagues but in reality these opportunities aren't easily come by so why worry, things wont change that much in 6th months. Yes I will be Jobless, homeless and probably a little work shy but helpfully I will return a decent and hopefully more enlightened and worldly person.

Please follow my new blog space to keep track of our adventures, I will update when can!

http://the-travelling-geek.blogspot.com/