Github Pages

I have for long wanted to do something with Github Pages. I have seen cool projects having great websites for promotion and acting as landing pages and frontpages to Github repositories and the integration just seems to come so easy, but I could not really find the time to have a crack at it.

Then I read a Github blog post stating “Publishing with GitHub Pages, now as easy as 1, 2, 3”, so I think, well know it must be about time.

I have had a plan to do some promotion of the repository and Perl distribution Workflow. But I wanted to do some experimenting first, to get a feel for the process, tweaks and tricks and the result.

I started with my personal Github page, then that and my Today I Learned repository. Utilizing the available themes was quite easy, but that would mean that your site/page at some point look like everybody else’s and the point of doing promotion is to stand out.

I have several Perl distributions on Github, I would for them to have some sort of resemblance so they would be easily identifiable as homepages for Perl distributions. MetaCPAN can utilize a link to a homepage using CPAN Metadata (See the specification: CPAN::Meta::Spec, resources).

homepage.png

Getting this set using Dist::Zilla was described in my latest blog post.

Well I decided for the Cayman theme and I decided to go for some basic customisation.

Github Pages uses Jekyll and adding a theme is quite easy doing it via the Github repository settings.

settings.png

I am a complete n00b at this Jekyll stuff and I am primarily programming and not doing layout using CSS and HTML – I am one of those programmers who love Bootstrap. But I successfully got Jekyll running locally.

Anyway I forked Cayman repository and got it working so I could do changes, tweaks and customization.

When I finally got the “Cayman” theme to look like what I wanted, I ported my changes to me repository using the Cayman theme following this piece of documentation.

The actual porting is quite simple, but I had to translate from some Sass directives to pure CSS. This was done using a combination of inspecting elements using the browser and copy-pasting CSS directive from my fork of the Cayman theme.

Lifted from the documentation referenced above:

custom.png

My final result got to look as follows:

---
---

@import "{{ site.theme }}";

.page-header {
  color: #fff;
  text-align: center;
  background-color: #fff;
  background-image: linear-gradient(to bottom, #1e6bb8, #fff);
}

.main-content {
    h1, h2, h3, h4, h5, h6 {
        margin-top: 2rem;
        margin-bottom: 1rem;
        font-weight: normal;
        color: #222;
    }
}

And you can see the result here: https://jonasbn.github.io/perl-test-timer/

Apart from getting to learn a bit about Jekyll, Sass, I learned a bit about CSS3 gradients. I know my customizations are in the low end, but as I stated I would love to do something, which could communicated that it was a Perl 5 distribution, but the Perl 5 brand is somewhat vague – so the next step is to spark some creativity to take this new customizations to a new level and if it is going to be widely used for my distributions, perhaps be folded into some sort of standardised theme, which can be easily applied to several repositories.

If you want to help me create a Perl Jekyll Github Page Theme – ideas and suggestions are most welcome…

 

Github Pages

Public Specifications FTW

Please note that this post is by no means endorsed by my employer, it is a personal reflection on a strategic move I have participated in, in my line of work as a professional software developer.

The above paragraph, which I felt I a need to write as a part of this blog post, is very aligned with the actual post topic in itself, please read on.

The place where I work have for a long time published specifications on some of the offered services. Either this was done using our CMS or using PDF artefacts from a Wordprocessor.

Both processes where tedious and held several issues:

  • Content in CMS
    1. Hard to edit longer documents with figures and cross references
    2. Version control was not obvious
    3. Drafts compared to published documents was not used
  • Wordprocesser artefacts
    1. Version control practically non-existing or external
    2. Document control based on files shares, folders and naming conventions
    3. Manual publication proces

There was probably several other issues I have happily forgotten, like PDF meta-data removal etc.

After having done a lot of open source work in Markdown and on Github and in conjunction with releases of some open source demo clients for our services, I proposed that we published the accompanying public specifications on Github.

This proved to be a very clever move.

It did require some consideration on our side and it was quite a new move to us. Yes we had published specifications for public availability for long a time, but putting these in a public repository was still a new move for us. But the concerns hastily evaporated and the proces became natural and incredibly productive compared to the old processes.

At the time of writing we have 6 open sourced specifications and 3 clients accompanying these and a repository with XSD files supplementing one of the specifications.

Not all of the specifications are finished, but they are out there, so if somebody wants to see what is going on, they are most welcome. We have only received a single pull-request and that is completely okay. We do not want somebody to write our specifications, that is our job, but corrections to sample code, clarifications and of course spelling corrections are most welcome.

Here are some of the pros I have observed:

  • Using Git and Markdown
    1. Version control is built-in
    2. Markdown is quite powerful and easy to edit
    3. Syntax highlighting of code samples (bash, XML, JSON, text etc.)
    4. The flow resembles a development flow and the toolchain is somewhat the same
    5. Tagging of versions and complete history is available
    6. An engaging proces supporting pull-requests (oh well)
    7. Branching for new editions and proposals for change requests

Currently one of the specification has 4 branches, when evaluation and review is finalized, will be merged onto the master, which can be tagged as the authoritative specification – and this proces is so easy to grasp and complete since it is same proces we use for source code.

One last benefit I really enjoy, one which I think is a bit underestimated is – the contract.

When we publish a public specification, we aim at to be informative, useful, correct, exact, educational, clear and to the point.

This works quite well and since often I find that we refer to the public specifications when discussing topics related to our services and since the quality of these sometime outshine our internal specifications, I often find myself thinking that we should publish much more, much much more.

So revisiting the opening paragraf – ever so often we are afraid and publishing API’s become a side-project. Do not be afraid to publish your specifications and documentation, do not be afraid to use an existing platform and toolchain, the pros outweigh the cons and you will quickly forget all about the old way of doing things and you will find yourself more productive and in the end getting your specifications published will be easier than ever.

Whether you are publishing a website or a PDF document, the information is public, the proces is actually the most important aspects and Github and Markdown REALLY leverage this.

The discussion on how far you can go and how much you can publish is a huge topic and should perhaps be another blog post.

Public Specifications FTW

TIL

I fell over something on Github called TIL (Today I Learned). I have for long pondered to migrate my notes elsewhere – currently they are all collected in a Wiki.

The idea of TIL intrigued me and now I finally got a TIL repository set up. Currently it only contains one TIL, but I plan to evaluate and migrate my earlier notes to this more open and accessible format.

Here are some of my first impressions of doing TILs hosted at Github instead of something else.

  1. The are public available
  2. They have native version control (they are actually contained in a Github repo)
  3. The can be written in Markdown
  4. They can use syntax highlighting based on the languages supported by the Github platform
  5. They follow the normal workflow used for other projects I have hosted on Github
  6. They can be forked and merged
  7. They can be commented on using issues (not directly linkable, but I guess it is somewhat trackable)
  8. Did I mention they can be written in Markdown 🙂

I have not observed any major draw-backs of this kind of write up to now, some will probably show later on, but I will give it a try and if it does not work, well I can find some other way of hosting my notes, hints, tips and tricks.

Only one TIL, but I promise more will follow.

Take care,

jonasbn

TIL