Monday, February 15, 2016

Weeklies 2 - Documentation

So I spend this weekend writing up some documentation for the flexbillet-api. I have done no research what-so-ever, and this makes for a nice point!

While not-researching, I actually wrote some documentation. My thoughts kept coming back to "there must be a tool to automate some of this", but instead of exploring, or even start writing something up, I just did it. And there it is: https://github.com/nwillems/node-flexbillet-api

So why was the documentation important? 1. It would suck to put something out there, and then have nobody able to use it, 2. The feels - giving something back, and then proudly publishing to NPM. Yes its on NPM, this little gem(ahem..), https://www.npmjs.com/package/flexbillet-api

This is my first published module on NPM and it feels really great. Thinking about it, it seems completely unreasonable, but it feels good.

So the actual documentation, if you look at the commit history I did quite some iterations. Recently I've been introduced to squashing commits, but this time I felt that it would defeat the purpose. It sort-of documents the documentation process. The documentation is split in three parts: Installation, Simple usage and reference docs.

The installation is easy, it is also the shortest part, it also makes a lot of assumptions, you should be somewhat familiar with the terminal and the node ecosystem, or at least be able to translate it.

The "simple usage" is the most straight forward part, also the hardest part for me to write, simply put it should boil down the module to a single piece of code that shows you that it works, something you could copy-paste and have working within 5-minutes. I think it succeeds in that.

Finally the "reference doc" should be a comprehensive list of the methods provided and their expected behaviour. This is the time-consuming part to write, first ensure that the method is tested(and fails), then implement it correctly, then have the test produce output, now add the inputs and outputs to the documentation, factor out common objects(See Generally defined objects), and lastly contemplate wether you should start an effort to structure the returned output differently, or maybe make it more of an exploration for the user...

And this is where I leave you, with a list of next weeks topic - testing.

EDIT: This post should have had a GIANT kudos to the NPM people, https://docs.npmjs.com/ is an awesome site, I never thought it would be so easy to publish something to NPM. Awesome job guys!

Sunday, February 7, 2016

Weeklies 1 - Writing a wrapper API

At the moment I'm trying to get moving on a small project, it's called DigiKreds(Yes, like DigiMon, but instead of monsters it's for local Scouts organisations, in danish "Kreds").

The first thing to note, is that we recently got access to a new system for handling trip-invitations and payment(https://flexbillet.dk/). And I got access to their API description, ya great customer service.

First of all, my language of choice is Javascript, so its going to be a node module. Second, I would like the interaction to be as clean as possible, meaning that you should configure the module once and then use the methods provided. And speaking about methods, the API is sort of REST, which is nice. But then again, this is no advanced system, thank you developers :-).

So I got off to writing some code, which was the goal. Wee, lets hope I can push myself to do something similar during next week, and suddenly "a wild language binding appeared". For now the code is just a bunch of failing tests and no actual outside world calls, so its nowhere near being public, but in a short few iterations its going to be.

While looking into this, I started my internal monologue about RPC vs REST. There are certainly cases where RPC makes more sense, or at least its easier to implement. Just thinking about the classic calculator example, do you POST to the add-resource, or how? Please feel free to leave a comment on this topic, I'm eager to learn.

Weekly 2: documentation

EDIT: Remove sign-of and add link to following article

Tuesday, April 29, 2014

Notes on installing Archlinux

This blog post is a collection of notes, for installing a modern Archlinux system.

Networking

I had a minor problem with the networking. It simply required restarting the dhcpd service for the given interface:
    systemctl restart dhcpd@enp2s0.service

Partitioning

The system has a 250G drive(Shows as 232G), and is GPT with the following scheme:
SizeTypeMount point
200MEFI System...?
50GLinux/
80GLinux/var
102GLinux/home
Suggestions found at: https://wiki.archlinux.org/index.php/partitioning

Base package installation

    pacstrap -i /mnt base base-devel

Needs to remove reiserfsprogs(maybe also xfsprogs,jfsutils) after installation.
Maybe stupid question but why libldap, libsasl and openssl ? openssl is pretty basic yes, but why in the base system?

Generating /etc/fstab

Should /boot come before /var and /home or does is at all matter to spend time mounting boot when using UEFI? Of course it should be mounted when doing sysupgrades, but otherwise?

More updates to come!

Sunday, December 29, 2013

The toughest job aka creating server/client certificates

The reason why is pretty unimportant, and frankly I don't know what I did to have it working. But suddenly it did.

The task is to have an apache server use SSL with client-certificates for authorization. No problem, you just create your own CA, issue a server certificate, issue a client certificate and convert to PKCS12-format for consumption in your favorite browser, right? Not so fast!

So I made a gist walking through the steps: https://gist.github.com/nwillems/8172932

My starting point was this: https://code.google.com/p/migrid/wiki/ServerInstallNotes#Certificates_-_Manually

And intermediary process has been a lot of googleing seeing all sorts of procedures to accomplish something similar, and then not yet. Some resources has been:

That pretty much sums it up - have fun authenticating with your new certificates. 
Have a happy new years :-)

/Willems

Friday, May 3, 2013

An app idea, pre configured cooking timer

Today I was making coffee and I had this idea about an app.

Because making coffee is a "long" process, you most often don't want to stand and wait for it to finish. So what if you could just once record the time it takes, and then next time you make coffee you just press the "I'm making coffee"-button, and your phone will beep when coffee is ready.

For my coffee "machine"[0] it takes about 11 minutes, another thing is the coffee machine at work and a third thing could be boiling an egg.

It could replace your good old cooking timer[1], and save you the trouble of turning it too little to make a loud and clear ring.

Letting the ideas flow, I thought you could make it such that a picture of what you are "timing" would be a sufficient lookup. Such that the flow would be something like, take a picture of coffee maker, stop timer when coffee is done, next time you make coffee you just snap a picture of the coffee maker and voila it starts the timer. I'm no image-recognition guy, so I have no idea if this is feasible on a regular smartphone, but sure seems like a nicer way, instead of having to either type or scroll through a list.

The idea is of course up for grabs, if anyone feel for making such a thing. I would be proud if you mentioned this post.

/Willems

[0]=One like this: http://2.bp.blogspot.com/_186GvjLpfrQ/TUm6oKldzRI/AAAAAAAAAdY/eE639i8IQHo/s1600/NewMokaExpressLarge.jpg
[1]= http://img.alibaba.com/img/pb/080/061/279/279061080_599.jpg

Tuesday, April 23, 2013

Managing a project on Github.

A short post on managing code via Github. They probably have a thousand articles and this has been written a million times before, but I'll write it to remind my self, and  as a nifty reference for my group in "Company project"(I guess there will be some sort of post about that).

Thursday, August 9, 2012

Pacman short usage

Finding pkgs:
    pacman -Ss | less

Removing pkg:
    pacman -Rnsu

Install
    pacman -S

Do YOU need more short commands? Put them in the comments and I'll follow up.

PS: I know this is written from the blogger interface - my own is broken :(

Choose a month: