Documentation Artist

I saw a recent job posting for a Documentation Artist on Authentic Jobs and my interest was immediately piqued. What is a Documentation Artist you ask? I asked the same question and after reading an entertaining job description it became clear that this was a position for a Technical Writer to write technical documentation for the lister's product Temboo.

What caught my attention past the title of the position was the way in which the position listing was crafted. The tone is such that it conveys the understanding of good technical writing and how important it really can be.

You could argue that your product should just be good enough that documentation isn't required. That is certainly true for an application like Draw Something, but there are a lot of situations and a lot of products where documentation is an absolute requirement. Some products or services essentially depend upon their technical documentation. Temboo is a good example. It's a different product by almost everyone's standards that deals with some pretty technical stuff. Documentation is crucial to at a minimum give people a kick down the right direction.

Writing the how-to step-by-step guide for anything is a pretty straightforward task. Just start with step one and write what you do until the task has been completed.  The thing is, we've all had to wade through some impossible to understand, unbearably dry documentation to only end up exactly where we started. It's frustrating and will definitely turn people off from using your product or service. So maybe it really isn't that easy. Maybe there is actually an art to writing technical documentation.

Technical documentation has a reputation for being flat out challenging to get through. That doesn't need to be the case and it shouldn't be this way. No matter the subject why can't reading through your documentation be at least mildly entertaining? The subject nature of a lot of the things technical writers write about are inherently dry, but I think there still can be things done to improve the experience of using the documentation. And a side benefit from some delightfully useful documentation is that you enable your customers to better use your product. When people are able to easily take full advantage of your product or service and have actually enjoyed learning about it you've created some advocates of your product. It may seem like time wasted when you'd rather be concentrating on building your product, but if people aren't able to take full advantage of it you're missing out on a lot potential business.

It's cool to see a company make such a big deal about a role that in a lot of situations either gets totally overlooked or at a minimum ends up getting pushed aside. Technical writing is tricky and the real great writers are able to communicate complicated things in delightful ways to truly enable end-users. This is most certainly an art and deserves to be thought of in that light.

Here's to the Documentation Artists.

Ideas of March

I stumbled on a blog post written by Meagan Fisher entitled Ideas of March. Aside from it being a great read it also raised this thought of the Ideas of March. I explored further and discovered that it was in fact a call to arms. A call to revive blogging and it was now in it's second iteration this year. It got me excited and made me think about some things. Blogging has seen a growing importance in my life so I'm jumping on board this train.

I think this is really a good thing to both the community and blog writers and I'll throw a couple thoughts out there as to why.

Writing is a newer thing in my life, but it has quickly become a large part of it. In fact, it is now an income stream that I depend on from month to month. More than that a majority of the writing that I'm doing is for blogs. So to me, blogs are directly important. I used to sort of sluff off that idea of professional bloggers and now I'm straying into that territory and realizing its legitimacy. As I do more writing on this site, my personal blog, it turns into essentially a portfolio and can help me to get more work and allow me to practice my skills to become a better writer.

Blogs have given way to other forms of self expression on the Web in recent years. This call to revive blogging is a direct result of this cultural shift. Things move so fast in Internet time so it's hard to necessarily grade the level of this issue, but I think bringing it to light and getting people to think about it can only help us all out.

We're sharing more and more and we're writing original things less and less. The whole Curator Code thing that cropped up in recent weeks is evidence of this. Some folks want simple sharing of content (not their own) to be considered curation and they want credit for finding that content. I won't go into that any further right now, but you can see my thoughts here. I think it's fighting the wrong problem.

Sharing has over-taken creating original things. I'll throw myself right into that mix as well. I've spent plenty of time on Tumblr sharing random things I've found over the last couple years. It's a blast and I'm not going to stop doing it, but what I am going to do is make more of an effort to create much more original content both here and elsewhere. 

I'm not looking at this as a March project (obviously, March is almost over). I'm looking at this as a wakeup call to start paying more attention to creating original content however difficult it may be. I plan to be more open about things and sharing my thoughts and options here even if no one is listening. There's still a chance someone could stumble upon something I've written and take some value from it down the line. And writing in general is an amazingly beneficial skill in just about any profession or walk of life so more writing will only enable me to better myself.

So here's to the Ideas of March (and beyond).

Curator's Code: Fixing a Problem That Doesn't Exist

Curator's Code was released recently to solve a problem that I'm not sure even existed in the first place.

Attributing someone for what they created should absolutely happen, but Curator's Code isn't necessarily helping to fight that battle. It aims to help us attribute our sources or rather standardize the process for attribution.

Sounds good so far but here's where it gets hairy. We're looking to standardize the "via" or "hat tip" type shares which is an extra level or possible thousands of levels deep.

Here's a situation.

I find something great way down in the bowls of the Interweb and I'd like to share that with everyone. I grab the link to said thing and share it on my blog or Tumblr or Twitter or whatever. Now, I'm 100% sure that the thing wasn't created by the person I discovered it from so do I need to credit that person for finding it before I did?

This is where I don't get the Curator's Code. The Internet and World Wide Web were developed with the core functionality being the sharing of information. Granted we've come a long way since the early days and instead of sharing important medical information we're sharing kitten photos, but the core idea is still there. We're sharing things. We're linking to things. We're liking to links of things. It's endless and that's the way it should be and what makes it so awesome.

So in my scenario above, should I credit the person who I discovered that awesome thing through? Out of common Internet courtesy (it's a thing) I probably would. That said I don't think it is completely necessary. Where there would be more of an obligation is when the original creator is known. In that situation you should definitely give credit where credit is due. But to give someone credit for simply finding something out in the wild before I did seems stupid.

Rather than creating some odd standard with symbols why don't we all just agree to do our best to credit the original creator and past that you're just being nice by crediting the intermediary source. Curating cool things isn't super easy, but it's a hell of a lot easier than creating the content.

Marco Arment wrote about this as well and makes a few killer points when he talks about those "via" type links and what purpose they really serve. Most uses are superficial at best (see Maro's The Verge example). Links are placed in the article itself. That's arguably a decent attribution (I'm doing it here), but it's not perfect.

When a full piece is written essentially with the information from the source the likelihood of anyone actually clicking the link to the original piece is pretty unlikely. I'd encourage you to read Maro's post as he poses a lot of great arguments, but I realize you probably won't and I think he's fine with that. I'm continuing the discussion not stealing his thoughts.

Here's where we can draw some differences I think. In many situations (like Marco's The Verge example) a new piece is written using that source information to create new content. That's partially what I'm doing here and really what much of the content floating around the Web is. The content is original on its own and for someone that would like to dig a little deeper into the subject the option is there. I think that's pretty much in line with the nature of the Internet.

A true link type blog that does this is wandering off into sketching territory I would say. When you're regurgitating enough of the original information to remove the need for the viewer to click through you're bordering on stealing the content.

I think I've wandered into a conclusion. In leu of using some symbols (which I will guarantee get almost no adoption) let's just agree on some things.

If you're using some information from somewhere else to further an idea or as inspiration to create a totally different one then a simple in-line link is great. You've opened up a connection and it's up to the reader to go down that avenue. As I mentioned, you should read Marco's post, but the reality is that his post was inspiration for this post and the ideas in it can stand on their own.

If you have a link blog, then your sole purpose should be to entice the viewer to click on the link and go to the source of what you're sharing. If you want to add a "via" attribution in there, fine, but it isn't necessary as the link itself isn't useful. To get the value you need to click the link to see the content. Attributing is funneling viewers to the source.

Really, we're back to where we started. Just don't be an ass and steal other people's stuff and try pawn it off as your own. Don't hide your sources and give credit where credit is due. Simple as that.

Opinion Entitlement

It's interesting how many people, when communicating (that's a loose term in a lot of situations) on the Web become almost an entirely different person. All of a sudden the need to share opinions rears its ugly head. I think it's pretty obvious that this is both a good thing and a bad thing. It'd be hypocritical of me to say otherwise. After all, you're reading my opinion right here. What I want to talk about is the almost resentment for those that intentionally close off the avenue for opinions to be shared.

I was listening to a recent episode of the 5by5 podcast called Back to Work. In it this topic comes up briefly and Merlin Mann and Dan Benjamin discuss specifically how John Gruber is essentially hated by some people and a primary reason is that they feel like he shuts them off to sharing their opinions. Gruber doesn't allow comments on his popular blog Daring Fireball. He writes about what he wants to and essentially never gets into any sort of online back and forth argument that so many people on the Web just love. This makes people mad. Some people.

The issue is that people feel like they are entitled to this sharing of opinion. This is certainly a new phenomenon that came along with blogging and Facebook and Twitter and all that good stuff. Think about the time before these technologies and ease of sharing. Someone wrote an opinion article and published it in a book or a magazine or a newspaper and that was it. The piece was maybe discussed amongst friends at the local pub.

A Web discussion is often a fantastic method to connect people with interesting viewpoints from all over the world and to have an intelligent, insightful, respectful discussion about a particular item. That is good and the way it works a lot of the time. The bad are those loud, sharp-toned commenters and opinion sharers who are essentially yelling into a conversation for real good reason other than to be assholes.

I don't blame Gruber for not allowing comments on his blog. He'd get slammed with these types of "opinions" because of the nature of his writing. He is successful and opinionated and that no doubt rubs some people the wrong way. When the option to share is turned off, certain people are enraged at this perceived lack of respect. The reality is that he has every right to close it off.

For the sake of everyone, if you're going to comment on post anywhere on the Web try to add some value to the conversation. There's no need to be an ass and it pisses me off when your stupid comments show up when I'm Google-searching for fedoras.

Journaling App Journey

Writing a personal journal hasn't been something that I've always done. Even recently I wouldn't say that I've actually been journaling, but rather just writing each day. I've been doing 750 Words writings nearly every day for the better part of the last year. While the theory behind these is to do a brain dump in the morning to clear your mind for the day, these entries have turned into more of a journal that I write at some point during the day. At some point I realized there really wasn't a whole lot of value in returning to previous entries. That's part of the process of these writings, but I felt like I could get more out of it. I enjoy the metrics (totally accurate or not) that are automatically generated and there are some methods to track some other more custom metrics. I tried this for a while as there were some other things I wanted to track, but I quickly fell out of that habit.

With my new lifestyle I decided to try out an actual journaling application. There are many options in the field and the three I zeroed in on were MacJournal, Day One, and Chronories. 

MacJournal is very well regarded and after some research seemed to be a little more robust than I really needed. Day One and Chronories were the two finalists in my mind. Those were appealing for very different reasons. Day One is a barebones, impeccably designed journaling application that also has accompanying iPhone and iPad apps. Chronories is what you might call a new-age journaling application. It utilizes technology to accumulate data as well as allowing actual journal writing.

These are two areas that appeal to me. I love minimal, focused applications like Day One and I'm also really interested in the self-analysis Chronories would allow. After more deliberation than was healthy, I decided on Chronories. In the end I thought it would be most interesting to track some data about myself as a I embark on a career change and a big lifestyle change. 

I'm only a couple days into using Chronories, but here's a basic rundown of it's capabilities. Each day's entry is contstructed from a combination of automatically compiled data along with a little manual intervention. After a bit of configuration and adjustment, Chronories can record things like the music you've been listening to in iTunes, the people you've emailed and chatted with, the temperature where you're at, your mood, the applications you've been using and several other other things. Some of these items can be manually added to and tweaked to record exact what you're looking for. Along with all of this there is also a space for an actual written journal entry.

Some standard report type views are set up so that after you've accumulated some data you can look back not only from an entry by entry point of view (calendar view), but also from many other angles. You could correlate your mood to the temperature for example. That sounds pretty cool to me and the process to completing an entry seems quite easy considering the amout of info that is recorded.

Regardless of what application or method you use a journal is only useful if you actually use it. We'll see how Chronories goes, but the combination of automatic and manual entry should make the process easier. More on this as my journaling continues on this year. 

750 Words

Some time ago I stumbled on a theory or school of thought that involved writing 750 words the first thing of every morning. These are called Morning Pages, which is an idea from the book by Juila Cameron called The Artist's Way.

The idea is that you're able to sort of flush your brain out and work through any thoughts or ideas that you have fluttering around in your mind right away in the morning so that the ideas flow the rest of the day. It's a journal of sorts, which was something initially that turned me off about it to be quite honest. Then I discovered a Web application called 750 Words. The application provides you with a place to do your writing each day and then keeps track of the words you've written. It attempts to analyze your writing as well, which can be quite interesting at times.

The original idea for Morning Pages encorages the writing to be done right away in the morning and done longhand. It amounts to about three pages of writing. While the analog approach is kind of cool to me, and I have done some of my writings this way, I just can't make it routine. I'm at a computer all day so this electronic solution fits my lifestyle perfectly. And I'll say, while not completely necessary, the info nerd in me kind of enjoys the stats and analysis of my writing.

Buster Benson, the application creator, was nice enough to include some other dynamics in the application to encourage writing as well. There is a game element to 750 Words that awards you badges based on the number of days you've written as well as on your behavior. For example, you'll be awarded The Flamingo once you've written ten days in a row. While these aren't a huge motivator necessarily, they are kind of fun and I have to say I've gotten more encouragement from them I thought I would.

I haven't followed the Morning Pages method from The Artist's Way exactly, but I've found the exercise of a writing brain dump each day to be incredibly helpful. For me the practice of just writing down my thoughts has allowed me to process things much more easily and clearly. There's something to getting your thoughts down that brings light to them. Problems seem easier to deal with. It's easier to flesh out ideas or see their validity or stupidity.

An additional benefit to writing 750 words each day is that you're also honing your writing skills. The best way to become a better writer is to write more and let's be honest, we could all be better writers. Plain and simple. 750 Words allows you to monitor your writing and do so in a personal, private setting. If you're apprehensive about sharing your writing this is a perfect solution. I, personally, use it as an addition to my other writing.

I'll admit that I don't write my 750 words every single day, but I will say that I just feel better on the days that I do. I can notice a difference in my mindset during the stretches where I am especially committed. Over the last six months or so I've grown more and more attached to this writing and it has now essentially become a part of my day's routine. I don't feel right without it.

Whether your an artist or a writer or neither, the benefits of writing each day make trying 750 Words a no-brainer.

Word

From Steven Poole's article Goodbye cruel Word.

So that’s how it is now. I write within the pure, glowing universes of Scrivener and WriteRoom. I send articles to the Guardian as plain-text rather than .doc. I am confident that I will be able to open those articles and the chapters of my book again, if I want to, in 30 years’ time. And now a 1000-word review weighs 4K instead of 30K. I weep at all the innocent electrons I wastefully killed over the years, sending those massive, lumbering Word documents through the internet. I apologise for my particle profligacy. I have learned my lesson. Goodbye, cruel Word.

This is a great read for any writer out there or anyone that has spent any significant amount of time with a word processor for that matter. Word has gotten so bloated with features that almost no one needs on a day to day basis. Now I do all of my writing in a simple text editor (right now I'm using WriteRoom). My writing is device and applciation agnostic which is really almost a happy accident in my case. It wasn't something I thought about when making the swtich to a text editor.

Writing has become simple again and I love that. I'm not worrying about any fancy formatting, I'm just putting words on paper (er screen). When I first stopped writing in Word I felt like I was missing something when in reality I was gaining something. It's a little hard to pin down, but I feel more creative and efficient when I don't have that bloated interface hanging over the top of me.