If you’re a PAYMILL follower you may have noticed that a new Developer Centre came out to replace our old documentation a few months ago.
It may seem at first sight that changes are mostly cosmetics but in reality there’s more behind the scene.
Taking the leap
I had the idea for a while to make our documentation source available publicly on GitHub. Like many developers today, I’m using Git on a day-to-day basis. For almost anything. Not because Git is great (it is but Mercurial users could argue that there’s nothing so special there) but because GitHub exists.
There have been public code repositories available since people needed to share code but contributions to Open Source projects exploded with the creation of GitHub.
But it was still feeling a bit weird to imagine the source of a commercial service documentation being open to all … Until I saw Robin Johnson from SendGrid explaining how great this experience had been for them.
The process has not been easy since we had to create a new system meeting our requirements and migrate all the docs from their current format to Markdown so that anyone can contribute easily but I can tell you now that it was really worth it.
Benefits of an Open Source documentation
Internal contributions
Back in the day, updating the documentation was a process handled by some of our developers. Updating a typo would require to open a ticket, interrupt them in their project to process the ticket, and review the change. It was loading them with extra work and lacked flexibility and responsiveness.
Having the source on a central public place and as easy to change as editing text files allowed to switch the maintenance responsibility from a few people to anyone in the company. We are still a few with the ability to publish to ensure accuracy and consistency but things go a lot faster than before as most of the time we just need to read the change and merge it.
At PAYMILL we want everyone to feel concerned about user experience and a good documentation is an important part of it. With that in place I had the pleasure to discover that even my non-technical colleagues were willing to bring their contribution.
External contributions
Something that might seem very surprising at first is that contributions to the documentation are not only coming from the inside.
Users of the product are also happy to help. This is the way things work in our industry. We share knowledge on StackOverflow, we release our useful bunches of code as libraries. And we happily help the products we use to improve.
Think about it. When I find a mistake in a documentation or feel it’s really not clear if I can’t do anything about it I feel very frustrated. I will for example write a tutorial that I post on my blog which will send a clear message “this product usage is so unclear that users need to explain other users how to deal with it”.
On the other hand if I find out I can directly change things I feel involved and instead of being frustrated I’ll be happy to participate in building a great product with the company or community behind it.
GitHub based workflow
Additionally, having the sources of the documentation on GiHub allows a very easy and clean workflow.
First it’s really easy to track changes. We can see who edited which part of the docs, what was changed, etc.
It’s also easy to revert changes in case something was mistakenly modified. We just need to go back to a previous commit.
Offering contributions is as simple as cloning the repository, making the change and sending a pull request. Which means there is no author accounts to maintain. Authorisations are handled to repository rights as well.
Finally we are a technical company, and authoring through GitHub is a lot more developers friendly than a traditional CMS system.
You can find our documentation repository here: https://github.com/paymill/paymill-documentation
How does the magic happen ?
The system operating the docs is quite simple. There is a NodeJS server leveraging a static sites generator called DocPad.
When the documentation is updated in GitHub, a webhook is triggered on the system which causes an automatic rebuilding of the Developer Centre. Which means the changes are reflected automatically less than a minute after the modification.
Code samples are pulled from the SDKs repositories every time a new release is made.
The whole Developers Centre is a static website. It’s fast, reliable and very easy to host.
Conclusion: Worth the effort
After a few months in production I can tell switching to this system was really worth the effort, and our internal workflow improved dramatically. We are now able to respond to update requests much faster and some customers wrote us to tell they were really impressed by the reactiveness.
There is still room for improvement but we are very satisfied by this first experience.
So now if you find something wrong, please let us now directly on GitHub and if you feel like sending a pull request it will make us very happy.
Let’s grow the PAYMILL community together so we can offer you the best online payments solution.
Your feedback counts a lot so if you could spare five minutes to fill out this survey that would help a lot. Thank you for supporting us!
[cta-variant1]
