New Site Proposal: Technical Communication

Documentation is one of the main pain in the arses of most developers in any company. Either because they hate to write it and end up being forced to do it, or because they don't and the next coder in charge will find himself between a rock and a hard place while trying to solve a bug that should've been known already. 

Honestly, all parties are co-responsible for this issue: colleges hardly, if ever, teach students how to write short, meaningful documentation; coders will brush their responsibilities aside whenever possible; companies, mainly, refuse to bill and pay for hours spent on documentation because they don't deem it worthy enough; and managers tend to make it a managerial task, landing the responsibility on workers who don't have the proper skills to understand the coding mindset.

I'll start with a controversial example: Django's docs are widely regarded as among the very best in the world. In fact, they are so thorough and detailed that, when I decided to switch out of WordPress, I made it a priority that my new blog's CMS would have to be built on top of Django. Well, that's certainly great for someone who's completely new in web development, but, guess what? People who read documentation don't stay inexperienced for long. Within a few months, reading Django's docs became, well, annoying. At this moment, while I thank everyone who's ever written a single line of its docs, I'd rather go straight to Stack Overflow and look for a straightforward answer. 

On the other hand, I've just started playing with a new data visualization framework called Bokeh. It looks like a powerful tool for Python web applications, which will blow R's Shiny framework out of the water once (or if) it becomes competitive. Except that, while Shiny is easy to use and fully documented, Bokeh still links to assets that are no longer available

Of course, a community-wide issue will take a community-wide discussion to find the best compromise available. An effort in that direction would be the establishment of a Stack Exchange forum for Technical Communication, which is, fortunately, already on the works, but it needs your help to become a reality. If you can, commit to the proposal and help us get it out of Area 51:

Stack Exchange Q&A site proposal: Technical Communication

At this time, it already has completed 63% of its way to becoming a live beta, so it just needs a little push to get online. However, once it becomes live, it'll also become a private forum for a couple weeks, being accessible to just the ones who supported the proposal. In other words, now is a great time to get on board!



There are currently no comments

New Comment