17 Mar 2015
I am happy to report that Inch CI got a fresh coat of paint. For those unfamiliar: Inch CI is a service based on Inch that evaluates your project's inline code documentation and reports grades for each class, module and method.
First, here's the old design:
Although I really loved the look and feel of this first iteration (which had been online since June last year), I was always bothered by the cluttered CSS underneath and the fact that some additions, like the help section, did not really fit well into this design.
So I, by no means a born designer, set out last week to "re-imagine" the overall look and feel of Inch CI. And, thanks to Bootstrap, I was able to refresh the style of the site after about 8 hours of work.
I am really happy with this new look, that holds true to what made the original design great. In my book it improves both on the visual and the source code front, as the site lost about 60% of its CSS. And last but not least, this new form factor sets Inch CI up for potential extensions in the future.
Feedback on this and everything Inch-related is always welcome. Reach out via Twitter, create an issue in the project or simply email me (mail in Github profile).
21 Jan 2015
Here we go: Five not-so-technical tips to improve your documentation quality:
1. Docs are copywriting for hackers
Documentation should be an added layer of clarification, where the code can't speak for itself or is too far removed from where it is being utilized. This is why documentation is often interface copywriting; just not for the end-user, but your fellow coder.
2. Give copy-n-paste usage examples
People like fiddling around with code. IEX makes it super easy to see what your module/function does given input
A and how that changes given input
B. So provide some concise examples, so people can have some copypasta.
3. Keep it concise
Apropos concise: You can help people by writing in a concise manner as well. "Explain it to me like I'm five years old" is not the worst sentiment when writing docs. Alternatively, think "How can I describe this to my future self, who has not seen this code in a year?".
4. Only document public interfaces
This is kind of a given, but consider the implication: Think about what functions are public and which are private in terms of reading a documentation of your own code. Sometimes you discover that you have to refactor things just because the docs don't "read right" for how things are.
5. Keep it easily updatable
Your code changes, some parts churn more than others. Documentation has to be kept up-to-date as well, but you can mitigate the need for constant docs-updating by writing what the method/module is used for rather than describing what it does in nitty gritty detail. This way, you don't have to update the docs for every small refactoring.
23 Dec 2014
Before going into Holiday Hibernation Mode, I wanted to say Thank You!
Inch, my little hobby project to raise awareness for the importance of inline code documentation, had a wonderful first year and Inch CI, the complementary CI service started in June, has had a superb first sesaon and is now serving badges for over 500 open source projects on a day-to-day basis.
I am secure! :)
Last week, HTTPS was enabled after the issue came up on GitHub and I maintain a todo-list of things that I want to work on in 2015 whenever I find the time (better GitHub integration, additional languages, new design, ...).
This would not have been possible without the encouragement, feedback and kind words from the open source community. To all participants, contributors and constructive critics of this project: Happy holidays and thanks a million!