Archive for the ‘content management systems’ Category

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

 

Advertisements

Tech Tip: Websites on Github with Jekyll

We have been facing a challenge on how to manage the Styx Technology Group corporate website without having dedicated resources to host, deal with security, updates and maintenance. Having been in the website business for over a decade at the turn of Y2K,  having an easily maintainable solution was key for the long haul.

Enter GitHub pages (https://help.github.com/categories/github-pages-basics/), of course any decent software developer and team are using some form of version control, but the beauty is that it allows projects, users and organisations to have self hosted sites that are managed through a repository.  That in combination with Jekyll (http://jekyllrb.com/) supports content management without a database.

To further speed up our development process, we leveraged existing themes for the website look and feel that were close to our need, while keeping the site design very simple so that we focused on solving the problem at hand.

It was suddenly music to our ears as the team did not have to leave their IDEs (random plug for Jetbrains IDE tool suite that we have standardized upon)  in order to make updates to the website. Just create a new markdown document, verify and push … And bam!! the updates are done, version controlled and all, no more hassles with database configurations …

Need help getting your website up and running in such a fashion do shoot us an email at consulting at styxtechgroup dot com and we shall be happy to help and engage…. Have a great weekend

State of PHP Feb 2012 – Symfony 2, Zend Framework 2, IDE Support, MySQL

There is just too much going on so I thought I should put these thoughts down so that I do not lose my mind from the excitement and anticipation that comes from things moving very fast and innovation being spured at a pace which is mind boggling.

PHP

In my opinion the stabilization of PHP 5.3 which introduced namespaces (similar to Java Packages) was the first shot across the bow, and I expect 5.4 with traits to bring even more reusability. However our hosting providers are slow to upgrade most are still running PHP 5.2, without general availability for 5.3 just starting to appear

Frameworks

There are two main frameworks in the bull pen Symfony 2 (http://symfony.com/) and Zend Framework 2 (http://zendframework.com/) currently in beta. However they are as different as can be. While Symfony 2 has been refactored from a full blown framework to a bunch of core reusable components, its moving towards ZF2, in that its not trying to be all MVC, forms etc, but is rather a set of building blocks to provide web application framework. So good is it that Fabien Potencier the lead developer has a series on how to build your own framework on top of Symfony at http://bit.ly/zVLi7X

ZF2 on the other hand is a bunch of reusable components which you can mix and match with other frameworks which also provides an MVC, ORM etc.

If you have been in the Java world, Symfony is more like Spring Source () while Zend Framework is Apache Jakarta (http://jakarta.apache.org/)

Interesting tweet that sums it all up:
Every time a developer complains about php, the #Symfony2 community creates another great, namespaced, decoupled and reusable component

IDE Support

Zend Studio 9 was let loose at ZendCon, Oracle released Netbeans 7 (which supports ZF1, and Symfony), Eclipse PDT is chugging along, PHP Storm from Jetbrains creating  a storm with others  Vim, Notepad++, Sublime Text basically all you need to do is pick your poison.

Communities

Github (http://www.github.com) is the new Facebook and LinkedIn for developers, where all the action is happening for all the major PHP communities, you had better be there. Forking and making changes is as easy as a button press. I am yet to push my first commit to a project but I am getting there.

MySQL

The best know web database is getting losta love from Oracle, and also the community led by Percona, SkySQL, Monty DB, and many others. Where it seemed lost with lost of FUD during the $1bn Sun takeover by Oracle, it seems to just be gaining steam (at least from my viewpoint as a consumer, developer and user). Now at 5.5, with 5.6 starting to appear over the horizon …

While there is a barrage of NoSQL solutions, Hadoop leading the charge, MySQL provides a NoSQL interface via HandlerSocket (https://github.com/ahiguti/HandlerSocket-Plugin-for-MySQL) and MySQL Cluster (http://www.mysql.com/products/cluster/)

Supporting Infrastructure

This is where all the fun happens, who is using the language and what are the trends. Here is a snapshot:

  1. Content Management Systems – WordPress is getting lots of love, while Joomla now at 2.5 supports databases other than MySQL. Drupal is adopting Symfony 2 as its core framework while Magento runs off a modified ZF1 kernel, while XOOPS (http://xoops.org) is being rewritten to use ZF1 or two
  2. Template Engines – an area where battles are found won, and lost. Smarty now at 3.0 (www.smarty.net), has to battle Twig (http://twig.sensiolabs.org)  which is surging due to its usage in Symfony 2
  3. Web services – JSON, XML, AjaX, Rest Interfaces are no longer buzz words they are the norm with native support being baked into PHP
  4. Object Relational Mappers (ORMS) are one of the core developer architectural choices, in PHP we have ZF Table (Table Gateway), Doctrine 1 (Active Record), Doctrine 2 (Data Mapper), Propel (not used) in addition to plain old PDO all of which provide rich choices. Interesting is that Doctrine 2 provides an mapping for MongoDB which shows its versatility similar to Hibernate for Java
  5. Continuous Integration – with Hudson and Jenkins, and now Travis which is also hooked into Github provides a great way to continuously monitor the quality of your development
  6. Quality Control – PHP Unit has always been there but now we have mess detectors, and other metrics (do not make sense of them yet), but whatever you want to measure there is probably a tool for it.
  7. UI Toolkits – JQuery took the world by storm with JQuery UI providing a set of theme-able components, but we have HTML5 boiler plate and Twitter Bootstrap which are simplifying the cross browser issues we developers face.
  8. Performance – always a PHP problem but it has improved through 5.3 to 5.4, and other techniques like OP Caches are becoming more maintream, Memcache is pre-built into Apache …

Exciting times to be a PHP web developer oopsss we are not web developers we are Software Mechanics (http://www.brandonsavage.net/the-mechanics-of-code/)

Joomla Tip – Custom Content Integration with Jumi

Just wanted to share a Joomla (1.7) tip on how we were able to integrate custom content from an external web application with custom PHP code via the Jumi component and plugin (http://bit.ly/wWIQmz).

Joomla by default does not allow custom PHP code to be added to articles (content pages) functionality which is provided by the Jumi component. However in our case we also wanted to display the most recent report on the home page, plus the last 10 from the archives when the user asks to view more.

  1. Create custom PHP files to load the current report and one for the archives. These were placed in the Jumi component files folder. TIP Always include the PHP line  defined('_JEXEC') OR defined('_VALID_MOS') OR die( "Direct Access Is Not Allowed" ); at the top of the file to ensure that it cannot be loaded directly via HTTP.
  2. Create Joolma article with a Jumi plugin to load content from the external url. We used two calls to the url, the first one to load the latest report and executive summary and the second to load the archives.
  3. Use the excellent Gavick News Show Pro GK4 (http://tools.gavick.com/newshowpro.html) to load the article into a module position. However since we can limit the text brought back, we limited the text only to the first plugin call to load the latest report only. This will include a more link to display the current report and archives.

NOTES:

  1. When loading external urls we used the Curl Library (inbuilt in most PHP installations) since file_get_contents() is usually blocked from accessing external urls
  2. We could not use an external library as it seem like Jumi does not handle include paths very well, so we could not maintain configurations in an external file.
  3. When deploying into production, we had to set caching on otherwise the page loading took too long

Hope this helps you

OpenCMS Shell Export Issues – exportResources vs exportResourcesAndUserdata

Well it has been some time since I wrote, but it has been pretty busy over at work, with one issue after another to be resolved.

We have been having an issue with OpenCMS backups on the shell, even opened up an issue on the dev mailing list (http://lists.opencms.org/pipermail/opencms-dev/2011q2/035562.html) where the backups at the shell were smaller than those from the admin panel.

While pulling out my hair, have lost a bit this year, and reading all available methods I came across exportResourcesAndUserdata which does not seem different from the default method exportResources provided in the wiki, http://opencms-wiki.org/CMS_Shell. Maybe its all the caffeine, but why had I not seen this before.

It takes the same options, and I also remembered that on the admin panel during the database export I select the option to export account data, and voila the backups from the shell and admin panel are almost the same size.

Tomorrow, I am gonna try and carry out a restore to confirm whether I can access the data.

Thats a story for another time…

Joomla Nested Category Issues – Round 2 – Multiple Sections in Blog Layout

Well the problem still stands, my client has 3 levels of content and Joomla 1.5 only supports 2.

We have gone through most of the solutions:

  • Joomla 1.6 – totally unusable given the time and technical constraints,
  • Content Construction Kits (CCKs) like JSebold (http://www.jseblod-cck.com/) bring on more complexity than the CMS itself
  • Move to WordPress – interesting thought, we tried but the complex nature of the layout will require a lot of coding to bring it to life, we actually had a team member try this out

So we reviewed the client’s mind-map, and actually found out that although there were 3 levels of filing, the content was only located in two levels, so the to-level was a “faux” level and this could be simulated using the menus.

Now an issue cropped up, how do you display multiple sections in a blog layout. I give you a hint, use the excellent, I mean excellent News Show Pro GK4 module (http://extensions.joomla.org/extensions/news-display/frontend-news/7738)

For a complete solution description, checkout the Q&A at StackOverflow – http://tinyurl.com/5w5esza

Joomla 1.5 – Nested Category Issues

The things clients make you go through … We have been working on a rush magazine job using Joomla (http://www.joomla.org) , and all was fine until the client brought out their “Mind Map” (http://en.wikipedia.org/wiki/Mind_map) essentially a representation of the information architecture for their site. And like no other, they had 3 and 4 levels of content that had to be incorporated into the site.

Well WordPress, and Drupal were not options at this ti

Wow, I know Joomla 1.5 has only sections and categories, 2 levels, and you would need to move to Joomla 1.6. However on installing the simplest component, an RSS feed generator, the site breaks apart. Verdict – no Joomla 1.6, its not ready for prime time

After going through K2 and another content creation kit (CCK), I was ready to give up, until it seemed that jSeblod CCK (http://www.jseblod-cck.com/) would try to fit the bill. I was led down this alley because they had a Joomla patch for sub-categories, but was discountinued.

Well my team and I are going to thresh this out over the next few days and see if it will meet our needs, at least there is a dim light at the end of the tunnel

Joomla 1.6, the jury is out, but it will be at least 1 year, 2012 when we dare touch it with a long pole …

%d bloggers like this: