Posts Tagged ‘technology’

Building and Maintaining Technical Documentation – Markdown with Gitbook Tooling

Documentation, the word that brings cold sweats to techies far and wide, makes product managers roll their eyes but is the one essential ingredient in aiding adoption and usage of software tools and services.

A key mantra for software development and delivery is “documentation, documentation, documentation” while agile purists will take “Working software over comprehensive documentation” to mean that no documentation.

Obviously in today’s world the expectations for clients, is that software is key and must evolve quickly to meet changing needs measured in weeks, and not months. This fast paced change actually highlights the importance of documentation, but places pressures on it to evolve more rapidly, be easier to use and understand, while maintaining a trail of changes being made within a rapidly changing environment.

Many formats have come and gone over time, plain text,  HTML Help, Windows Compiled HTML Help (CHM), Oracle and Sun Help, Eclipse Help, Flash help not forgetting PDF and MS Word documents for printed manuals. The common practice was to use a single tool to develop the help that compiles into multiple help formats.

Fast forward and the model seems to remain the same, however the challenge being what markup language to use to enable generation. In comes Markdown (https://en.wikipedia.org/wiki/Markdown) which aims for readability (JSON, YAML) so that users do not need to know markup but provides a way of formatting with simple conventions. Interestingly at the time of writing this even Whatsapp one of the most popular chat clients uses markdown like formatting.

The formatting challenge has been solved but now how to build the content, version control it to keep track of updates, generate the content and share it with the world. The most common tools are:

  1. GitHub pages (https://pages.github.com/) – using a special branch within a GitHub based repository to build online based documentation
  2. GitBook (https://www.gitbook.com/) which provides an excellent editor, hosting, build for generating PDF, online documentation, and mobile format (.epub and .mobi). Just open an account, fire up the editor and you are good to go

However if you are using private repositories and need to keep content internal facing, then you need to pay quite a bit for GitBook or jump through multiple hooks. However GitBook fortunately provides a command line client which can be used in this case to build the documentation which is then distributed using internal channels.

The steps to setup a local Gitbook environment are:

  1. Install npm
  2. Install Gitbook cli by typing the command below
    $ npm install gitbook-cli -g
  3. Setup a git repository for the project and add the following files:
    • .gitignore – include the _book directory in which the book will be generated
    • book.json sample below
      {
        "title": "My Book",
        "description": "Description",
        "author": "Author Name",
        "gitbook": ">= 3.0.0",
        "structure": {
          "summary": "SUMMARY.md",
          "readme":"README.md"
        }
      }
    • README.md the default information on the book
    • SUMMARY.md the Table of contents for the book, which may be in different directories recommended is a docs directory
      # Summary
      
      * [Introduction](README.md)
      * [Chapter 1](docs/chapter1.md)
      * [Chapter 2](docs/chapter2.md)
    • package.json – contains build commands for the book
      {
        "scripts": {
          "docs:prepare": "gitbook install",
          "docs:watch": "npm run docs:prepare && gitbook serve"
        }
      }
    • The final project structure looks like

      Screenshot 2017-03-27 11.13.13

      Example gitbook project structure

  4. You can view the book locally by running the command below which starts up a server running on port 4000

    $ npm run docs:watch

  5. Commit the contents to your git repo

I have to say that I love the GitBook Editor which works way better than my IDE, so after commiting the intial files, I fire it up and open the directory containing my project so that I can edit the files from there. Obviously I lose the ability to put high quality comments on what has changed in the files without jumping back into my IDE or git command line, but the sacrifice is currently worth it.

Additional Steps to Generate ePub and PDF

  1. Install Calibre (https://calibre-ebook.com/download) which provides the ebook-convert utility
  2. Add tasks to the package.json as below:
    {
      "scripts": {
        "docs:prepare": "gitbook install",
        "docs:watch": "npm run docs:prepare && gitbook serve",
        "docs:generate-epub" : "gitbook epub ./ ./_book/mybook.epub",
        "docs:generate-pdf" : "gitbook pdf ./ ./_book/mybook.pdf",
        "docs:generate" : "gitbook build && npm run docs:generate-epub && npm run docs:generate-pdf"
      }
    }
  3. Generate epub by running the command

    npm run docs:generate-epub

  4. Generate pdf by running the command

    npm run docs:generate-pdf

  5. Generate both epub and pdf by running

    npm run docs:generate

UPDATE: More information on the GitBook Toolchain  can be found at https://www.gitbook.com/book/gitbookio/docs-toolchain

UPDATE2: Added steps to generate epub and PDF documents

UPDATE3: Discovered that the process has a name – Documentation Driven Development, which is pretty interesting concept … https://twitter.com/brnnbrn/status/847197686042312704/photo/1

c8hzw6qu0aayg2r

 

Tech Tip: Reducing pain while moving from Yahoo to Gmail

Its official that Yahoo has been hacked, http://www.nytimes.com/2016/12/14/technology/yahoo-hack.html?_r=0, and it is time to make that change from Yahoo to another email address. For a free service, looks like Gmail is the best there is at this time.

My quick guide to reducing the migration pain is as follows:

Step 1: Start adding your Gmail to all correspondences and signatures, plus start giving it out instead of yahoo

Step 2: Setup your Gmail to start receiving email from your yahoo address see How to Access Yahoo! Mail in Gmail

Step 3: Respond to all your correspondences via Gmail

While the cut over is immediate, to get your correspondents will take some time to finally start using the new address, probably 3 to 6 months, so be patient

Future of Software Development Industry In Uganda – 2015 Edition

These are my thoughts on the future of the software development industry in Uganda, after the official announcement of ThoughtWorks closure of the Kampala office (http://info.thoughtworks.com/Kampala-office.html).

I would like to approach this first of all by analyzing the contribution of ThoughtWorks to the Ugandan technology space, then what I see the future as.

ThoughtWorks contribution in two aspects – showing that its possible to run a pure-play software development business operation out of Kampala using Ugandan based talent, and the second providing an injection of new DNA into the local technology community. The exposure to international level processes, practices and projects have helped grow the experience of the local software development talent.

Local communities have been started & supported, included but not limited to Agile Uganda, Geek Night, Girl Geek Dinners (yay! Women in Tech), Rails Girls and Ruby Fridays. The OpenMRS community run a number of events to help grow its reach, while the Technology Radar discussions provided a continuous look into the present and future of computing. The contributions leave the local technology space different from three years ago.

What does the future look like? A tough question, and my answer is biased by over 15 years experience writing software in Uganda, my overbearing optimism, and my newly rekindled foray back into software development.

The future is bright, but can only be harnessed if the business and technology communities work hand in hand to grow the local technology capability. In this, a concerted effort to build a local technology practice with buyers pushing for a local component on all contracts leveraging open source. A good example is the Ministry of Health selection of OpenMRS (http://openmrs.org) as the EMR of choice for electronic medical records throughout the country with aggregate reporting done in DHIS2. There are lots of opportunities in leveraging technology in the agriculture and education sectors which remain new frontiers to be conquered.

I would further call upon the government entities and parastatals KCCA, URA, UMEME, NWSC to leverage OpenData approaches to provide the infrastructure for young innovators to build and monetize customer centric products and services.

Like Ghandi said, be the change you want to be in the world in this case “Coding in Uganda, for Ugandans, by Ugandans”.

Gakyali Mabaga (it is just the beginning)

Uganda National Housing Census 2014: Completed, Results Out but What Next?

The Uganda National Census has wrapped up. Or has it? Really not sure, but my household is a statistic for the next 10 – 20 years as a basis for planning. There are outcries of enumerators not reaching some areas, children answering questions for households and the general apprehension that the census exercise is just a waste of time.

Census information is a great help for national planning process, however in order for the statistics to be useful and relevant, it is important to continuously update and trend the statistics against existing circumstances.

The one disappointment that I find in the entire result is that the only statistic being reported is that there are 900,000 more females than males, but there is no breakdown or context or analysis of the number. What other statistics or data point can be derived from the numbers?

The question in my mind then is what else can be done to improve the process till the next census and how can technology be leveraged?

– Over the next 10 years regional data collection centers need to be setup to collect data trends over time to update the overall survey. This will leverage the national backbone infrastructure to provide a centralized location for data capture and hosting with localized analysis.

– Civic education for the population on why the information is being asked for, and what the importance is. I still wonder what the number of mobile phones, donkeys and wheelchairs as assets provide to the overall picture. The advertisement process should have been started over 6 months before the exercise, however it was barely noticeable that such an important activity was happening. TV and radio were used, but social media, SMS based options could have improved the coverage.

– All the questionnaires were coded, but the data entry still had to be done, with the advent of $150 tablets, couldn’t this process have been done electronically especially in the towns to cut down data entry errors? The tablets could have been setup to take GPS coordinates to ensure that the enumerators were not filling in the sheets while under trees (common survey issue) providing an opportunity to kickstart electronic data collection in Uganda

– Follow up on missed enumeration, using GPS coordinates overlaying satellite maps along with the white chalk reference numbers would ease the process of identifying and following up households that were missed during the enumeration.

Apart from technology, the following areas were not catered for:

– Enumeration data changes: what the basis for changing the data collected is, how the missing data will be extrapolated where need be, how the new data sets are going to support planning going forward

– Post-enumeration follow up surveys: to collect additional data to correlate the results of the census, as well as pick up localised data points such as transient populations (refugees, migrant workers, nomadic movements), local economic activities, which may not be important nationally.

– Local council authorities owning the census enumeration processes and results in their areas, and raising the bar by verifying the data that comes from their regions

Overall the 2014 census took place and the data is being released. However it is time to take learnings from this exercise and use them to put infrastructure and processes in place improve the next one.

Utilities can Leverage Technology as a Competitive Edge

Utility companies are virtual monopolies in the sectors that they operate, however the stifling regulatory oversight coupled with fierce attacks from startup based innovation requires rethinking of how customers perceive and receive value.

Technology can provide a catalyst for utility companies to improve their service, defend their positions and develop new business models to remain relevant in the future.

read Utility Services can get a lot more smarter with these Technology hacks for more ….

Uganda National ID – Alternate Strategy?

I have been thinking – some would say that is a dangerous thing, well yes I have been thinking, just what an afternoon with no distractions can do for you. Well there is a general problem in my motherland Uganda, there is no National ID. Oh yes, there is no way of uniquely identifying each and every person in the country, even tracking the babies born or the deaths. Sad but true, how has this affected the populace, to some its a great thing not to be known but to others, its a great source of discomfort since everything is just too hard to do.

What is not helping are headlines like Government suspends national ID project again and with a budget now growing to the hundreds of millions of dollars, a question pops into my head. Are there no other options to get to the same place, are there no other ways? In the words of Benjamin Franklin “If everyone is thinking alike, then no one is thinking.”

So again with the Snowden revelations, and potential for mis-use, there is one fact that is evident, with no National ID, the progress we are making going forward is going to be very very painful. In the software development world, there is the concept of “technical debt”, which has very high interest rates in terms of cost of addition of new feature, slowing down progress as you move along.

The high-level strategies revolve around the following themes:

  1. Frugal Innovation – how to use very little to make alot of progress
  2. Customer Value – focus on ensuring that the 75% who see the value are immediately served, to act as a tipping point for the rest
  3. Relevance – ensuring that the implementation is relevant in today’s “environment”
  4. Accuracy and Trust – the data within the system must be trusted from the word go, it should be easy to spot and very inconsistencies

So here it is:

  1. Target population – above 18 years of age
  2. Implementing body: a government parastatal & accompanying bill which is setup to manage the process of issuing the National ID numbers as the single source of truth whose mandate is to provide the lowest common denominator for citizen registration
  3. Who gets National ID numbers first? The element of trust is very important, but the need is to start with as little as possible to continuously refine over time, so the starting issuance of National ID numbers has to start from those people who are known, by different systems so that their identities can easily be verified which include:
    • Passport
    • National Social Security Fund
    • Tax Identification Number
    • Driving License
    • Voter Registration
  4. Registration of Births and Deaths: this is a critical component of the National ID system as it identifies which IDs are no-longer in use
  5. Regional Offices to ensure that people applying for IDs do not have to travel to Kampala to do it
  6. Technology/Organization:
    • Provide a means of checking the status of application by visiting authorized centers which include regional offices, SMS requests (responses to be sent to the number registered on the application)
    • Access to online verification services for authorized usage
  7. Critical Success Factor: uptake which can only be driven by the network effect of being used by multiple players within the private and public sector as the lowest common denominator for accessing services

What do you think? Where are the gaps that I have not thought through? What other alternatives are there?

HTC Desire HD – My Journey

HTC Desire HD

HTC Desire HD

This is a review, a journey of enlightenment (that sounds so Zen), learning, and eye opening experience for a techie who has not used a smart phone at all. I am still in love with the Samsung SIII, and that is essentially my next smartphone …. but in the mean time I will love what I got, the HTC Desire HD. I still have my Nokia C200 which well works for 3 days, without need for a recharge, has primitive Facebook and Twitter so hey I got lots to compare with 🙂 Did I mention that the HTC and Nokia phones use the same data cable, well now that is a welcome feature since I can cut down on the cabling on my desk and travel bag.

The first thing I do for any computer that I get is upgrade it, thankfully the phone has inbuilt WIFI so all I did was turn on WIFI, and use the office wireless connection, now that is really neat. When I checked the HTSense 3.0 was upto date and the Android version 2.3.5 was the latest. There was no way to go any higher due to the 512MB ROM which was too small, again acceptance. Next step was to install Tweetdeck, yes, no Facebook since I am on a 30 day no Facebook diet, and I seem to be handling it very well btw.

Email next, both my work and personal email are Google, so I just fired up the pre-installed Gmail APP and we are off to the races. Syncing took a long time and later I found out why, my personal Gmail box is “big” with all sorts of emails, Linked In, Twitter, Newsletters, GitHub, MojoLive, GeekList, etc, so I configured my personal Gmail to only show emails from the priority inbox which makes it manageable.

Next test camera, but oh no, it does not work. Seems like the delivery man (who brought me the phone) decided to take the only thing that would not be missed, the microSD card, really!!! Now I gave up on that one till I bought a 2GB card, then wow!!! The camera is really good! Crisp clear photos

Still on the battery problem, seemed like I had turned on background sync for Twitter and Gmail so now I turned them off, installed Juice Defender following steps at  http://www.stephenjackel.com/2011/04/16/how-to-fix-battery-life-problem-on-htc-desire-hd-android-2-2-mobile-phone/ I still got my eye on the battery life.

Oh yes next battle, sharing my contacts with my Nokia, it has been my primary phone for over a year now (lovely feel and battery life), so I have a couple hundred contacts, which I have rebuilt after losing them a few weeks ago when the battery went dead and deleted everything. Using Google I found instructions at http://leetstreet.net/blog/2011/05/nokia/ which let me export all my contacts from Nokia into Google Contacts, and just sync them into the HTC. So all I need to do is add new numbers to the Nokia and HTC, and I am done, how so handy it has become that I add business cards as I get them from meeting to meeting ….

It seems like I am a fanboy, but I love the contact linking between Skype, Whatsapp, Google and my contact list, and I assume that once I get another Android gadget they will all be transferred to it, which is nyce given that all is then stored in the cloud.

Customizing the screen pages, well I love my right menu on my Nokia which gives me quick and easy access to the same menu items I have used for the last 10 years, Inbox, General Profile, Silent Profile, Task List, Calculator and I am done. I have mulitple tabs on Android so on my main screen (like my old feature phone) I have got Gmail, Twitter, Messages, Call historry, Contact list, opera mini and the default browser, Whatsapp (I find myself using it more and more). Now on the second screen I have got other common utilities, Camera (great quality), Gallery, Reader found books on here though I have failed to connect to Kobo for more books, iStoryBooks (a gold mine, my kids are loving my phone and wait eagerly to get at each book that I have downloaded), calculator, wordpress statistics for my blog, Google Talk, Flashlight, Google Playstore, Calendar, Evernote (trying to use it to share notes across everything), and Skype.

I also ran into a problem of syncing my calendar with my phone with the creation of duplicated events. This puzzled me till I remembered that I already have 2 way sync between my Google Calendar and MS Outlook, so syncing both with my phone creates two events. This one was cleared using instructions from http://sysadminspot.com/phones/delete-pc-sync-calendar-on-htc-desire/ So once that was done all I had to do was turn off the Outlook calendar event sync from HTC sense on my laptop and voila!! It was all good to go. So now I create an event in Outlook it ends up in Gmail and on my phone and vice versa, and I love it. So no more birthdays forgotten or events missed.

And oh yes I have been introduced to the pain of Internet bandwidth data caps, I found that I ran through 100MB in a week, yet I only use the mobile data when I am out office, I use the office WIFI when in office. I found that the cheapest bandwidth 30MB which is valid for 24 hours for 10 days is the same cost as 100MB which is valid for one month. So I will need to find a way to automate my daily purchases so that I do not have to go through the 6 steps to get around the USSD codes.

The major challenges, that I am still running into are battery life which dies after an hour or two of heavy use, when I go out for meetings so it’s tied to a USB port on my laptop, left the 240V power charger which uses USB too at home to make sure I have my bases covered. Also I found that using the power charger gets it full while the USB charger does not move it along as fast.

So HTC love your phone, but there is terrible battery life …

%d bloggers like this: