The talk

You have a reasonably well founded position, you almost certainly have enough to write about. You have arguments and counterarguments for the major things people are going to say. You have experiences that no one else has. So just write them out. Who can argue with what you have experienced? You’ve already done the hard work of thinking about this problem, why not get the benefits of writing it out? If anything, this will help clarify the thoughts that you have.

The specific phrases don’t matter, as long as you are getting out the main thoughts. You can always refine it over time—the great is the enemy of the good here. That’s what the edit functionality is for. I know you would love to include a beautiful graph or venn diagram to illustrate something, but just say it now and add it later if you must.

There is this nagging thought that says, “what if someone on the internet thinks I’m WRONG??“. That’s a vestigial fear coming out, like being worried about tigers or alpha male chimpanzees. The more rational concern, and the one you should focus on, is “does anyone even know that I exist?” The only way to solve this is to write.

You’re worried about being controversial? That is a good problem to have, it means someone cares enough to write a reply. And if you are wrong? Well, you learned a lot quicker than you would have if you kept it to yourself. Seems like a good deal.

Just ship it.

Just ship. Other people might want to read it. That publish button is scary? Just schedule it for two days from now or next week and keep on writing in the meantime. You’ll have forgotten all about it when it publishes and be surprised when someone asks you about the new post. “Which post?”

Writing might be the single best way of spreading knowledge that you have. It just makes everyone better off, including you. Instead of rehashing the same stories and thought patterns in your mind and with others, just write about it and refer them to the article.

Don’t have much time to write? Put down a nugget of inspiration for later. Just put the minimum intelligible sentence, and maybe instinct will take over. Just write it up real quick while you are thinking about it. You can surely find thirty minutes to just write what you’ve been thinking about or reading about. Could it be considered productive work if you are publishing something that will help your business grow?

Lastly, it might help someone else out a lot. It doesn’t take all that much time and you will feel better having done it. When you look back on this year, the posts that you have written are going to stand out in your mind as a high note. You will get better at writing and the next post will be even easier.

Wrap-up

Meta-reservation: I was worried about publishing this post. Then I scheduled it for a week and a half away.

Phew, that was quite a pep talk.

If you ever want something to write about, let me know and I’ll try to help out!

Original article: How to Write Without Reservations

Immediacy and Inspiration

It’s more useful to write about experiences at a recent conference right now instead of two months from now. The time delay not only dampens memory, it also weakens excitement. It definitely helps to write about things when I am first excited or think about them, because once the enthusiasm fades it feels more difficult.

Topics that I once thought were fascinating are no longer so after I have been exposed to them for awhile. Strike while you are inspired with learning, because after that energy passes, you are less likely to be interested in it because you have already internalized the concepts. It’s hard to get fired up about something that you see as obvious. Here is a great summary of this idea.

I internally model this as your brain being in roughly a steady state. Something comes around that shakes up your mental models, and the resultant attempt to put your brain back into equilibrium causes a great deal of energy to be put off. After this happens, it’s tough to recreate the level of energy that happened, and it’s also hard to difficult to remember what your brain state previously was.

This goes back to Steve Pavlina’s concept of writing within 48 hours of getting the idea:

I don’t maintain a list of article ideas, I don’t actively brainstorm ideas in advance, and I generally don’t ask for suggestions. I’ve done all of those things in the past, but they don’t work well for me in practice. At one point I had a list of about 200 new article ideas. When I scanned it for something to write about, I was usually bored by everything on it.

If I get a suggestion from someone for a new article, I’ll normally write about it that same day if it excites me. Otherwise I simply let it go. Ideas by themselves have no value to me. There’s an infinite supply of ideas. The present-moment inspired ideas are the ones worth exploring.

Inspirational energy has a half life of about 24 hours. If I act on an idea immediately (or at least within the first few hours), I feel optimally motivated, and I can surf that wave of energy all the way to clicking “Publish.” If I sit on an idea for one day, I feel only half as inspired by it, and I have to paddle a lot more to get it done. If I sit on it for 2 days, the inspiration level has dropped by 75%, and for all practical purposes, the idea is dead. If I try to write it at that point, it feels like pulling teeth. It’s much better for me to let it go and wait for a fresh wave. There will always be another wave, so there’s no need to chase the ones I missed.

Why Writing Backlogs Are Harmful

One problem with maintaining a backlog of things to write about is that the overhead of managing all of those ideas. There is too much work in process, and thinking about too many things causes thrashing. This reminds me of my post on limiting reading work in progress and books in progress.

Keeping a backlog of writing ideas becomes especially problematic when a long lead time between when the ideas are written down and when they are implemented occurs. Often I’ll forget what I was thinking about when I wrote a nugget for a post seed. Or I will read a book and have to re-read parts of it to get the context back. This process causes waste.

It’s certainly possible for cutting-edge ideas to become stale over time. This is also a form of waste.

Of course, it can be tough to get important things done while making time to write. Queueing by utilizing a backlog is one potential path, but a better solution seems to be more frequent and regular writing. By just sitting down and getting the ideas out there right after a new association is made, better writing can actually happen with less effort.

I think having less of a backlog contrasts a bit with the Fieldstone Method of Writing by one of my favorite authors, Jerry Weinberg. However, there seems to be some overlap, in that action with inspiration is easier than action without inspriation.

Do you find that you have too many ideas for posts, or too few? If too few, do you want some ideas?

Original article: The Case Against Writing Backlogs

Here’s a demo of what I envisioned using a recent blog post that I wrote using the following method.

The system uses git for version history. I also used a Vim hook that checks in the current file on buffer writes:

cabbr autocommit call Autocommit()
fun! Autocommit()
  au BufWritePost * silent !git add <afile>
  au BufWritePost * silent !git commit <afile> -m 'Generated commit'
endfu

This is about the finest grain of editing that I can imagine being useful and that was practical to do. Anything lower-level and you’re probably looking at the document as the cursor is moving around. Commits are nearly instantaneous, and you can amend commits to explain complicated changes. Git branching seems to work well with this system. Hence, you can have multiple streams of writing. If you’re working with other people, you could be writing a new chapter when you get some feedback on the last chapter which you would like to add. Simply create a branch from the time that you sent the document out, and you should be able to see exactly what the reviewer saw. In addition, authors of collaborative works can use the push/pull functionality to manage copies, which is probably better than emailing documents around. See this page on collaborative writing for more ideas.

As far as the current visualization goes, I used a Ruby suite that I found called DocDiff. I think that this based on or uses wdiff, a difference engine focused on words. Based on my understanding, wdiff writes each word to a line and uses the standard GNU diff algorithm to detect changes. Anyway, DocDiff seemed to fit for a rough visualization of the changes between each commit, so I used this and hacked together the navigation with some further scripting.

Improvements could include at least:

• a more accurate diff function
• showing diffs in the opposite direction when you go backwards in time
• representing branching
• advancing changes automatically instead of manually
• showing sections moving smoothly in real-time
• Doogie Howser typewriter noises
• highlighting backgrounds a different color when the final words used are in their correct places
• showing commit information in a corner for context
• showing the product over time based on the source (think PDFs with images)

For blog writing, I’ve been pretty happy sticking with HTML, although Markdown would probably be better. For longer works, I have recently found Pandoc, which is a Haskell-based Markdown-and-more implementation with fewer bugs than the standard Markdown interpreter. You get support for other file formats, conversion between file formats, and the ability to write documents to PDF using LaTeX! LaTeX is nice for editing large works, but it can be cumbersome to read at times. Pandoc allows you to use Markdown for most things, and then switch to LaTeX mode for things like equations. Markdown seems to play well with versioning and seeing changes over time as well.

Non-programmers

I pretty much agree with all of the points Derek Hammer brings up in Personal Source Control. On a Linux machine, I would contend that git is pretty painless to set up, although you still need to realize that you’re starting something worth tracking. It’s not automatic yet. Plus, there’s the learning curve of actually using the system. It’s not fully in the background. And to the overall points, I definitely think that putting your local files and documents under version control is a great idea. If it’s so easy that users don’t need to think about it, then it’s an advance.

I read a book a couple of months ago called About Face 3: The Principles of Interaction Design, and the authors talked about going to a more document-oriented user interface model. The book gives some interesting examples to why this is a good idea.

Pretend you have never used a computer before. Would it be intuitive to rename the word processing document you are currently editing by clicking “Save As…” and saving it as a different file and then deleting the original? I think this makes little sense because thinking about files is more of an implementation detail than how people actually think about their projects. I don’t really care if the computer is storing my document in a hard drive, the cloud, or a shoebox, I just want to be able to rename a file I currently have open.

Versioning of documents should undergo the same analysis. Manually choosing to track changes and then being inundated with the visualization is a chore. And when users forget to track changes…? Complex merging is a chore regardless of how diligent users are.

While I was looking for a system that would check in text files automatically and push to a central repo when I was ready, I saw an article about flashbake, a git- and cron-based system of recording writing changes. While I’m not all that interested in what song was playing when I committed, having contextual information might be helpful in some cases.

Google Wave has a pretty nice way of replaying waves (conversations) that resembles the revision tracking system in a wiki. I could see using this for a personal knowledge management system when it comes out. It’s definitely nice because it should be accessible from many different platforms as long as you have an internet connection. One downside for me is the fact that you are not in full control of the data (backups, privacy, security.)

As far as collaborative text editors, I’ve looked into Gobby for some work projects. It had the best quality that I saw, you can see everyone in the session typing in real-time with different colors and no locks, and it’s cross-platform compatible FOSS.

Other thoughts

Here is an article about using relative dates. This seems like a helpful concept. Instead of saying that I read About Face a couple of months ago, I could put in an approximate date and then let software do the translation. This might be nice so that people know that I’m probably not interested in talking about the book when they stumble upon this post in a couple of years. Many things on the internet are time-specific, so anything to state this clearly seems to be moving in the right direction. I can’t think of how many times I’ve read something and thought, “this doesn’t seem quite right,” and then looked for a date and realized it was horribly out of date. Using more relative dates is a semantic web thing.

I’d like to see even more histories of documents on the web, with linking to specific versions of documents. This would enable programs to cache the documents that you link to, and if the contents change or have newer versions, you can be alerted to this fact so that you can update your references. Instead of having fully broken links when a page is down, your web server would just fall back to the caches of the documents. This would all but ensure that useful pages are backed up in a distributed fashion. People seeking to restore a lost site or link could run some sort of script that is aware of sites that are backing up external sites, and link to those caches, adding further redundancy. This reminds me of Linus Torvalds saying (hopefully tongue-in-cheek): “Backups are for wimps. Real men upload their data to an FTP site and have everyone else mirror it.” There would obviously be logistical hurdles to overcome if someone manually changes their cache, if versions get out of sync, etc.

While we’re at it, let’s add transparency to government operations. Consider every change to every bill in the legislative branch and every signing statement having an associated author, time, and commit message explaining the rationale. Then citizens could see who really makes positive changes to bills and who to hold responsible for the pork. Are you sure you want to release a hundred changes one minute before voting is to begin on the House floor? True “blame” and “praise” (from an SVN perspective.)

Original article: Writing and Revision Control

I appreciated feedback that people gave me over the course of the year, whether through comments or discussions. This helped me realize that I can provide value through writing and that people are actually interested in reading what I am thinking about.

I now think that being creative is something that one can improve with practice. I don’t think that I seriously considered this angle before trying to produce something creative over a long period of time. Being able to produce consistently is a challenge, but once I started doing it, my mind changed to accommodate this request. When I gain new insights, I start thinking about how I can formalize these thoughts into something that is digestible for other people.

I’ve noticed this in songwriting or poetry as well recently. I don’t think most artists just sit down one day and say, “I’m going to write ten songs today.” The way I imagine it goes is that they write songs continuously and then take the ones that resonate most strongly afterward.

By and far the most popular two posts have been the Pomodoro Technique post and the Vim Word Processing post. Based on Google Analytics, I’m thinking the former is popular because people are searching for things on the Pomodoro Technique, and the latter is popular because it is linked to from the popular Vim Autocorrect plugin page.

As noted in some of the notes sections, I have work to do with limiting WIP and getting things out while they still have energy. Again, as written elsewhere, I realize that having a word target is good, but writing every single day is probably more trouble than it is worth. Writing with energy is important, as is writing out what I am thinking about and just getting it on paper.

Looking forward to another year of thinking, writing, and interacting! Thanks for tuning in.

Original article: Annual Navel Gazing

It seems that their goal is to improve the documentation of free software products to increase their adoption. You can check this out on the about tab. The discussion on their FLOSS manuals overview reminded me of thoughts that I was having about having some sort of open source documentation or tech writing business. They basically outline the major models for producing content and being compensated for it. There were several sections that focused on the prevailing mindset, technologies, and economics of doing open source (in this case, for free software) documentation. I agree with them that adequate and consistent documentation is something that keeps most open source and free software from being widely adopted on the desktop.

There have been some free software products out there that have been very widely accepted, such as Firefox. I wonder if it is because the program itself was leaps ahead of the proprietary alternative, or if something else contributed to its success.

Original article: Free Software Documentation

You can swap it with a different function that you use all of the time. I recommend switching it to the escape key. You can also change it to function as a control key. But why would you want to do this?

Benefits

First, the caps lock key is modal, which means that much mayhem can result from misplaced keystrokes with the caps on, especially when working with complex text editors. There is little visual and no tactile feedback on the state of the caps lock. This inevitably leads to annoyances when the lock is on. There’s a reason that login dialogs always warn you when the caps lock is on.

Regardless of your text editor preferences, you stand to gain quite a bit from making this change if you use the keyboard even to a moderate degree. Imagine that an annoying dialog pops up and instead of clicking on the close button or invoking alt + F4 or sliding up to the Esc key, you can instead quickly disregard the window with a mere slide of your pinkie. When an application informs that you have unsaved changes on closing, pressing escape is a lot faster than figuring out which of the buttons on the dialog correspond to “please don’t disregard my changes.”

If you’re a Vim user, you stand to gain much more utility from having the caps lock key stand for ‘escape’ instead. Firstly, inadvertent caps lock use will kill you in Vim. Most of the normal mode commands are case-sensitive, so instead of going down ten lines, you’ve just concatenated the next ten lines. Whoops. Second, escape is the function that you invoke to get from whatever mode they are currently in to the normal mode. You press escape a lot. The saving here comes from sliding your left-hand’s pinkie finger over a tenth of an inch instead of having your hand travel two or more inches. Over the course of a year you will save about eight million miles. Instead of using the crufty caps lock key, you can just select a section and press “U”, and then the section will be converted to uppercase. That’s if you don’t want to hold shift down for like five seconds.

On the other hand, if you’re an Emacs junkie or general keyboard user, you might consider remapping the caps lock key to a control key. This is probably still more useful than the caps lock, and moving it up an inch makes it more accessible.

If you don’t like it, you can always go back! You can also remap something you use even more rarely (like the scroll lock key) to function as a caps key. But I get by fine without any caps.

So how do you do this?

For linux, I would try this tip. Another good start is doing a web search or going to this c2 page.

Drawbacks

It takes about a week to get your muscle memory fully used to this. It takes longer if you have multiple computers that use different or default bindings. Once you get used to it though, you will be hooked.

If other people try to use your computer, they will be stymied in the unlikely event that they want to use the caps lock key for its intended purpose. So don’t let them use your computer.

Original article: Caps Lock Remapping

I originally felt this parallel when I constructed arguments for essays. Words and sentences must be read through sequentially and the work needs to make sense. This resembles writing a program and running through it in your head before executing. When writing a paper, I found framing arguments often corresponded to declaring variables. The introduction of a paper lines up with initialization, setting the evaluator’s mind in a specific state for later communication. The conclusion is cleanup. Pronouns are abbreviations or aliases to entities. A sentence that could be ambiguous should be expanded out, much like one would use parentheses to clarify a potentially ambiguous expression.

I suppose the common thread between writing and programming is logic and the ability to read, reason about, and judge the source. Obviously the brain is a more fickle interpreter.

This insight makes me wonder about development analogies for writing. What would test-driven writing be like? Could we codify knowledge like: “This sentence presupposes this paragraph to make sense.” Continuous integration for writing? How about collaborative writing with version control and branching?

Original article: Writing Is Like Coding

Weinberg always seeks to move writing forward, and keeps a list of things to do depending on his energy level and state of mind. If he feels high in spirit, he might develop fieldstones into new sections. If he feels drained, he might reword a section that needs fine-tuning or perhaps take a break.

Weinberg’s technique seems to produce a volume of writing: he has published over forty books and numerous articles and other writings.

When reading through his description of the Fieldstone Method, I was struck by the similarity to my own writing technique. I tend to collect insights, thoughts, quotes, and articles that I find interesting and repurpose them in later work. I call these nuggets instead of fieldstones, but the concept is generally the same. They are raw materials for writing, things that strike me as useful but need explication. Typically when I write for other people I use these as a basis and then expand upon that until it likely makes sense for my audience. Parsimony and unambiguity are criteria to consider, with preference for the former for blogging (long posts don’t get read.)

This method significantly increases work in progress. My current blog draft count is half that of my published posts. Many of these are just plain nuggets, like a hyperlink or a sentence. Some have a few quick arguments or thoughts. A few are probably politically unpublishable. Still others are nearly done or completed. Hence, I need to strike a balance between writing what I feel energetic about and finishing articles that I have worked on. Weinberg recommends not writing about things that you are not interested in. This is different from sharing things that you have already learned and believe that others will be interested in.

I think the real power here comes because subconscious creative juices are not consistent. I only get one morning shower per day where inspiration hits. The key seems to be writing down nuggets whenever they strike, and then consistently fleshing them out afterwards. Keeping a journal or log of thoughts helps.

This method also works well with limited time constraints. If you have an hour a day to write or you commit to one hundred words, it’s nice to be able to write about something that interests you that day. Longer periods of time might be necessary for harder sections or cleaning up tough spots.

I found these quotes helpful:

The stone itself is not the key to effective writing. The key to effective writing is the human emotional response to the stone. As a writer, if I respond to a particular stone with tears of joy or sadness, I know that others will, too.

If I don’t respond, my readers probably won’t either. That’s the secret of the Fieldstone Method: Always be guided by emotional responses, or, as Fieldstone writers say, by the energy–the heat that coal provides when it burns inside of you.

I’ll have more to write about energy in the near future. For now, finishing this post.

The most important book you’ll ever have for your writing is the blank book, or the scrap of paper, or the card, or some modern electronic capture device that you have ready for writing down this reference.

Always be ready to capture. Inspiration strikes at strange times. You will forget insights that you have if you don’t immediately write them down. In the field, I email myself and star it for adding later to a permanent file.

Original article: Fieldstone Method of Writing

I would go so far as to say that there should be open source technical writers. They look for interesting projects to write basic documentation for. While there are a smattering of tutorials for certain frameworks, they are not condensed, are not authoritative, and are often misleading because of changes to the framework or convoluted examples. When the core developers move at the speed of the forum or even IRC, it’s tough for a new person to have anywhere near that amount of knowledge. A centralized wiki with pertinent and up-to-date examples is quite useful.

If you are not yet a badass developer, this kind of project aids you in three ways. First, you gain experience looking at unfamiliar code bases and reasoning about them. This is especially helpful if you maintain code, and also assists you in writing more maintainable code. Second, you get some street cred for being closely involved with the developers on the project and working with them. You’re likely to learn something from the alpha geeks and advance your skills. Third, your writing skills improve, which helps you out in many areas over the long run.

In a nutshell, the kind of people who are building their own system or framework are generally not obsessed with documenting for average people. This could be due to time constraints or general personality traits. But the value that they create is wasted if people are not comfortable interacting with it.

Clojure

There is an interesting thread on the Clojure discussion group about making examples readable and general ways to help developers who are new to the language and want to code idiomatically. One post mentioned the Clojure page on concurrency. If you can read through the example code there and want to tackle concurrency (which is supposed to be a strength of Clojure), then I applaud you. This isn’t a knock against Clojure, it’s just so new that most everyone who’s interested has been playing around with it and trying to understand it better.

One of the most important points in the post is that to get a community rallied around a language or framework, it’s necessary to have good documentation so people aren’t put off by it. The Clojure folks are getting there, as there are a couple of wikis around that people dump stuff into.

qooxdoo

The qooxdoo framework illustrates one of my favorite examples of excellent open source documentation. When I first started looking at it, I was impressed by the amount of examples, pictures, screenshots that were included. The manual is rife with examples and code snippets.

They have a huge demo area that shows how simple effects can be created using at it. Looking at these demos, I started visualizing about how exciting it would be to work with this framework. As another great demo, it has an API documentation viewer, which itself is written with qooxdoo. It must have taken time to generate all of this…

Parting thoughts

On the other hand, one could argue that with a nascent open-source product, having too many people involved early is problematic for direction and quality density. Also, the people who create code which uses the product will constantly have to change their code because the underlying architecture or best practices change. It’s the bleeding part of the bleeding edge.

I’m not saying that I’m committing to doing any of this… Just thought that this was an interesting line of thinking.

Original article: Open Source Tech Writer