Tag Archives: Programming

by Ben Trube | November 20, 2014 · 8:08 AM

“Perfect is the enemy of the good”

Both professionally and as a writer I am bumping up against this aphorism in my current projects.

One of the things they tell you as a writer is to keep revising, keep changing, keep editing, keep making the book better. The same is true of software, though unlike writing often the process is keeping up with changes other people are making that affect your work (I’m looking at you Microsoft).

The first thing I learned as a professional programmer was the difference between the ideal perfect solution, and the practical, applicable, “quick and dirty” solution. On deadline you don’t have time to make flawless code. And truthfully flawless computer code is a lot like haiku’s: not very long and can only express a few things.

Writing is much the same way, especially if you want people to actually read your stuff. Eventually you have to reach the point where it is okay to put something out the door. If you’re constantly rewriting based on your evolving standards (changing user requirements) you will never deliver a product. This is not to say you should send something out that is half finished and buggy. Even though ebooks are becoming more like software in that you can push updates out to everyone who purchased them, you still have to deal with initial market impressions of you. If you become known for making crappy software, or writing crappy books, no amount of post-release revision is going to fix that. Then your only solution is re-branding (maybe a pen name).

So how do you know when something is done? Maybe it’s a fixed number of revisions, or even more practically a release deadline. Maybe it’s finding that fresh beta reader who hasn’t read a lick of the draft and hasn’t already formed impressions of it telling you they love your work. Whatever the case, sometimes you have to accept something is good, and will never be perfect.

How do you decide when something is done, and when it needs a few bug-fixes?

As a side note apparently the above phrase is commonly attributed to Voltaire though it has its origins in ideas from Aristotle and Confucious. Thank you Wikipedia.

1 Comment

Filed under Writing

Tagged as Books, Programming, Revision, Technology, Writing

by Ben Trube | August 6, 2014 · 11:55 AM

The Joys Of Technical Writing

If you are a professional engineer, particularly one with a known interest in writing like me, you may be assigned to one of the more dreary forms of writing, technical writing. This can be anything from a project proposal, to a quick start guide, standards document, or the dreaded user manual.

I’m in the middle of drafting one user manual and updating another for my job.

But writing for a technical audience doesn’t have to be boring, and a lot of the tools that may work for your fiction writing project can be applied to your professional life as well. Here are a few tips and tricks I’m trying as I work on this latest “book”.

1. Keep using word count goals – Since writing a technical document can often involve a lot of external work, like taking screenshots, testing procedures, and fixing bugs, this word count goal may be more modest than you think. 1000 words of technical writing may be the equivalent of 3000 words of fiction writing for you. Whatever the ratio is, it’s easier to feel like you’re making progress against what can seem like a gargantuan undertaking if you keep these micro goals.

2. Don’t work too far ahead – There might be a temptation to use your afternoon taking screenshots and planning out the next chapter, rather than continuing to write. Sometimes this is fine, as it gives you an idea of the direction of your next section. But if you want internal consistency in your screenshots, and to show your procedures as a logical progression of one step to the next, you may be better off taking screenshots concurrently with your writing so you don’t have to do as much rework. This can seem disruptive to the writing process, but it reduces the amount you’ll have to go back.

3. Tell a story – If the piece of software is used to build something else, create an example project and use that project throughout the entire manual. Show how each chapter adds features to your project along the way. Be sure to explain everything you think needs explaining, but provide a context for that feature as well. It’s the whole showing not telling thing.

4. Have a little (appropriate) fun – I’m a math geek if you hadn’t guessed so you’ll see more than a few apt puns in example names in my technical writing. A common programming trope is the “Hello World” program or variable names of foo and bar (though these may not be appropriate in all professional contexts). As long as these puns aren’t excessive, and don’t detract from the overall usefulness of the document, they can be a way to make the writing more fun for yourself.

5. Have something else to do – As a software developer there are always bugs to fix and features to tweak. It doesn’t hurt to have a few of these in your back pocket to work on when you really don’t feel like writing. If you have a deadline, be sure you meet it, but make sure you get your brain thinking in different ways too. It will improve both aspects of your work. If you don’t have additional projects of your own, see how you can help someone else (again caveat emptor as your work environment may vary in terms of your freedom of development time).

6. Outline and write sequentially – A user manual will often be referred to in any order, so it’s important that each chapter be able to stand on its own. An outline will give you a sense of what other chapters to reference that are relevant to your topic, and writing sequentially allows for the continuing narratives of examples and back references to topics you’ve already discussed.

7. This is a living document – A fiction writer is used to the idea of revising and revising until something is done. Technical documentation (if it’s to be useful) is never really done. It has versions and revisions like software, and should be periodically updated. That’s why it’s important to have a structure you and others can follow so finding the sections to update is much easier.

What kinds of writing do you do in your professional life?

1 Comment

Filed under Trube On Tech, Writing

Tagged as Programming, Software, Techinical, Work, Writing

by Ben Trube | February 14, 2014 · 6:35 AM

Bonus Friday Post “Fractal Valentines Day!”

Many of you have probably seen this old XKCD comic:

But it takes a special brand of geek to see that drawing as a challenge. Here’s my first attempt and its axiom:

Unfortunately, L-Systems aren’t really designed well for curves. You can draw them, but you’ve got to do something like “move forward small amount, turn 1 degree, repeat 180 times”. In L-System code this looks like this:

“DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DF”

DF = Move D forward, E+ = Turn 1 degree

But this is Valentine’s Day, and Valentine’s day should be a little hard. So here’s attempt 2:

As you can see a little closer to the mark, but we’ve got some overlap and the heart is kind of pointy at the curve transition. For attempt three I did a trick I used to do with cakes. Take a square, and add two-halves of a circle to two sides:

And then because it’s me, I thought, “can we make the heart just a tidge taller”:

Now most people would stop there, but I played around with a couple of other variants:

And then I thought, well now that I have this heart object, what else can I do with it?

Here’s the code for “Heart 3” my first successful attempt, which works with the programs in Chapter 4 of my book:

<?xml version="1.0">
<lSystemSpec>
 <imageAttr prefix="heart3LSys" lvl="6" scaling="0.5"></imageAttr>
 <ruleMappings turnAngle="15" length="250">
 <rule cmd="forward" char="F"></rule>
 <rule cmd="right" char="+"></rule>
 <rule cmd="left" char="-"></rule>
 <rule cmd="begRecr" char="["></rule>
 <rule cmd="endRecr" char="]"></rule>
 <rule cmd="move" char="fg"></rule>
 </ruleMappings>
 <transformations axiom="Cg[X]BgA-TfRS-[X]S-RTfA-Bg[X]">
 <replace char="X" replStr="Cg[X]BgA-TfRS-[X]S-RTfA-Bg[X]"></replace>
 <replace char="f" replStr="F"></replace>
 <replace char="R" replStr="DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DFE+DF"></replace>
 </transformations>
 <variables>
 <var char="A" value="9"></var>
 <var char="B" value="4.25"></var>
 <var char="C" value="-4.25"></var>
 <var char="D" value="0.034906585039886591538473815369772"></var>
 <var char="E" value="0.066666666666666666666666666666667"></var>
 <var char="S" value="3"></var>
 <var char="T" value="4"></var>
 </variables>
</lSystemSpec>

Technically the “R’s” should be replaced with the whole long string and you can get rid of the R replacement rule, but I left it this way for readability. High-quality versions of the image are available by clicking on the image.

Happy Valentine’s Day, especially to you, the little red-haired girl 😉

2 Comments

Filed under Uncategorized

Tagged as fractals, Programming, Sierpinski, Valentine's Day, XKCD

by Ben Trube | September 6, 2013 · 6:35 AM

Fractal Friday (Julia: c = -0.708108+0.266986i)

Today’s fractal is a Julia set image, a fractal generated on the complex plane like the Mandelbrot set, but one determined by an imaginary constant c. Today’s constant was selected at random from the 40,000 Julia set constants my Mandelbrot scanner has come up with so far. All images were generated using programs from Chapter 6 of Fractals: A Programmer’s Approach (most last night during MasterChef)!

During the selection of the gallery images I’d typically create about twenty images for each Julia constant, 23 for this post to get 7 final images.

There are 250 gallery images in the bundle (probably about 60 of which were created using this process, so think more than 1000 images, not including those featured in the main text).

You want to select coordinates that highlight the interesting features of the shape. Julia sets tend to be most interesting in the center, though this one also has a couple of good spirals. I also like to dive as deep as I can in a single section to show the fractal’s self similarity (the bundle videos really illustrate this method). You also want to choose colors that frame the features you think are the most pleasing.