Technical writing is an art on its own, especially if English is not ones native language. My writing skills are far from perfect. However, there is a bunch of mistakes that I see (my) students etc. to repeat over and over. I will collect them here to help them to remember.

If this triggered your interest, please see here for a more extensive list: http://www.cs.columbia.edu/~hgs/etc/writing-bugs.html. Also, I like the book “Bugs in Writing” from Lyn Dupre.

Disclaimer

Please note, (1) my writing skills are far from perfect, I still do (too) many mistakes myself. (2) This may include the ones I list here :-). (3) As young PhD student my writing skill where even worse than now, I thank all the people who bared with me and helped me to become a better writer (This especially includes Stefan Götz, Klaus Wehrle, Tobias Heer, Jo Agila Bitsch Link, Hamad Alizai and many many others). Thus, any hints on mistakes I do in the examples below are very welcome :-).

Active Voice vs. Passive Voice

Passive Voice (do not use it): “The computational performance are shown in Section 5.1.”
Active Voice (yes, yes, use it): “Section 5.1 shows the computational performance” or ” We show the computational performance in Section 5.1.”

Figure 5, Section 3, etc. are Names: They need Capitalization

No: “We show the computational performance in section 5.1.
Yes: “We show the computational performance in Section 5.1.”

I.e. and friends.

No: “The world is flat, i.e. there are no mountains.
Yes: “The world is flat, i.e., there are no mountains.”

E.g. vs i.e.

Ask your favorite search engine

And

No: “A record contains a meter ID, GPS coordinates and a timestamp.
Yes: “A record contains a meter ID, GPS coordinates, and a timestamp.”

Sections etc.

Readers are afraid of surprises. First tell them what they will see in a specific (sub)section and then detail on it: “In this section, we first discuss the configuration options of the algorithm. Next, we employ a set of benchmarks to select options that both ensure a high performance and accuracy”. After such a short intro, go on and discuss the two aspects.
Similarly, a small conclusion / reflection / discussion is helpful at the end of a (sub) section.

Captions of Figures

No: “CDF of deviations in the data-set.
Yes: “The CDF of the deviations in the data-set. The plots indicate that independent of the experimental setup, pigs cannot fly”.
Thus, after noting the technical aspects of a figure, please summarize the take-home message of a figure/table/…: What shall a reader conclude from the figure? In the paper itself you then elaborate on the details, corner cases etc.

Advertisements

Installing TinyOS seems to be not so easy with Lion / Mountain Lion / Mavericks OS and the xcode. The following worked for me (using telosb / msp430):

Update Sep 2014: As TinyOS is pushing to next release, there have been numerous fixes to settle the Mac OSX issues that I list below. Thus, some issues might be obsolete by now.

Update October 2014: You find hints on OSX 10.10 Yosemite in the comments below.

1. Actually, I am not sure if one really needs this first step, I just did it along the way while figuring a way to make it all work. Install gcc 4.6 and gcc_select from macports and select gcc as default compiler for macports via “sudo port select gcc mp-gcc46”. When you are done with installing TinyOS, nesc etc you can disable this again by calling “sudo port select gcc none”. Update: based on the feedback of others: It seems this step is necessary.

2. Install msp430-gcc and msp430-libc via mac ports. At the time of writing of this post the gcc version was 4.6.3-20120406. Update: based on the comments, it seems that newer versions of gcc such as 4.6.4 or 4.7 do not work (yet?).

3. Load TinyOS from google code GitHub and put it somewhere. Set this path in tinyos.sh and source it from your bash configuration as both are described on the TinyOS documentation pages. Update: TinyOs is now on GitHub, and tinyos.sh seems not be included anymore. Thus, you can set the paths by hand or use  https://github.com/tschmid/tinyos-2.x/blob/master/tinyos.sh.

4. Load nesc from cvs head (neither nesc 1.3.3 from macports nor the tar ball from soureforge worked for me, while both compiled and installed fine they lead to errors when trying to compile TinyOS applications: “nesC: Internal error. Please send a bug report to the nesC bug mailing list”. But 1.3.4 should be out soon, hopefully this allows to install from macports/tarrball again). Compile and install as described in the readme for cvs installation (the readme says you need emacs and some other stuff, it worked fine for me without). Update: 1.3.4 has been released, and you can download it from the project website (http://sourceforge.net/projects/nescc/) and follow the install instructions. Update: If “make install” fails, make sure you run “./configure”, “make”, “sudo make install”. Update: NesC 1.3.4 and the latest code from github (https://github.com/tinyos/nesc) seem to work just fine (as long as you compile them with gcc — see step 1 — and not the default llvm-gcc of Mac OS X).

5. Install TinyOS tools: in the tinyos download, go to tools and run ./bootstrap, ./configure, make, sudo make install etc. (as described in the install instructions). You might have to fix the following on the way: In tos_locate_jre I had to set xcode_jdk=/System/Library/Frameworks/JavaVM.framework/Headers and in NativeSerial_darwin.cpp I added #include <string.h> and #include <stdlib.h>.
Upate: new paths for JVM:
jhome=/System/Library/Frameworks/JavaVM.framework/Versions/Current, 
xcode_jdk=/System/Library/Frameworks/JavaVM.framework/Versions/Current/Headers
Update: Hint: Also here you should make sure that you compile things with gcc — see step 1 — and not the default llvm-gcc of Mac OS X.

6. Install FTDI drivers: http://www.ftdichip.com/Drivers/VCP.htm. Interestingly, 2.2.17 lead to some errors during programming (BSLException: Bootstrap loader synchronization error). I took 2.2.16 (http://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_16.dmg) instead and it works fine.

7. Check that everything works: go to Blink and try “make telosb” and “make micaz sim”; connect some nodes and run motelist; install something (if it fails during programming noting that no module serial is availble in python, you might have to install pyserial via “sudo easy_install pyserial”).

There is an app for everything! Or at least for nearly everything. This means, traditional search (google, bing, …) will face some changes. We will not use search anymore to find cheap offers for a flight, a product review, or whatever else. For things that we do more or less frequently we will have an app do this. Hipmunk, expedia, tripadvisor, and many many more. These dedicated apps will be our starting point, at least from our mobile and from the tablet. As a result, search and related advertising might see a problem.

This also includes the desktop. For many things which we have been doing in the browser, we see more and more dedicated apps popping up: evernote, wunderkit, and many others give you an app for your desktop. As someone who has never been a big fan of doing everything in the browser, I am very happy to see us switching back from the browser to apps.

It is interesting to see how the social networks (facebook, twitter, google+,…) are evolving when compared to the original Internet: The social networks are a closed box, it is not really possible to connect one network to another. In contrast, IP networks or applications like email are designed open. Thus, any company (or private user) can connect to the Internet and communicate via open protocols. Or one can run its own email server that connects to other email servers via well-defined protocols.

Now, I know, that the user base of social networks to some extend is their capital. Hence, a lock-in maybe be wanted to a certain degree. However, when compared to the history of the Internet, I wonder whether this lack of interoperability etc. will hinder innovation and evolution. Based on its open architecture the Internet (and the PC) evolved quickly and provided a great platform motivating and fostering others try new ideas. Now, the APIs around the social networks also allow such new ideas, but they seem to focus on the “around”. Hence, the access to the core network is limited.

Overall, I wonder whether this closed architecture will hinder evolution and innovation in the long run. Maybe, once their usage patterns and applications stabilize, we can find a way to deeply interconnect the different social networks. This might also allow one to choose a social networks based on criteria such as privacy and functionality and reduce the pressure of being in one particular network just because everybody else is there, too.

Side notes:

1. I know that companies in the social network world are highly innovative companies. Running their own systems allows them to deploy new ideas quickly. Note, that my thoughts are more general.

2. This is not meant as a call for standardization: standardization processes as we know them today maybe too heavy-weight for this fast-moving area.

Some thoughts on the browser and  the OS: I believe that its is time to move applications out of the browser. There are too many things that we do inside our web browser, that we could do otherwise easier, better, and at less CPU load and network traffic.

The mobile devices show us the way to go: There are little apps for everything. With the App store for MAC OS, Apple also brings this concept to the desktop and laptop (Note, that Linux essentially had an App store since the first days: apt, yast, yum, and whatever they are called).

To me, the core benefit of these App concept is that I get a little application that is tailored to the goals of the application. Hence, it does not have to deal with the limitations of the browser in terms of languages, html, java script, ajax, flash, lack offline support, and until recently the lack of right clicks. It is just so nice to have a couple of little windows (standalone): one for email, one for notes (I love Evernote), one for Blog writing (such as Windows Live Writer).

In Google Chrome and especially Chrome OS we see Google addressing some of the issues by deeply integrating the OS and the browser. However, stuff still seems to be bound to the browser (and html etc.). Now, I know that html forms a great platform abstraction layer (you can view it essentially on all systems, throw in a mobile site of your stuff and it can be conveniently viewed on smartphones, too) and also forms a second “narrow waist” above IP (there is a HotNets paper on this). However, all this loading, rendering, scripting, is just too inefficient (sure, Ajax etc. help you with it, but still, this is quite a beast).

So, what does this mean for the browser and the OS. From my point of view, the OS (or services on top it), need to provide two features: (1) a Just In Time Compiler (a nice JIT compiler, best with Hotspot support) and (2) a html renderer. Both shall be common services shared across multiple active applications. The Compiler shall handle the efficient execution of all the scripted high level languages we are using today: JavaScript, Python, Flash (and all other Adobe stuff), etc.. Additionally, it can deal wit the byte code of Java, C# (and .Net in general), and all the other stuff. LLVM, .Net, and the new Java core show that this can be done nicely. The apps may use html inside for visualization where appropriate (see Evernote etc.). Hence, the html renderer will parse their html as well as normal web browsing sessions.

I believe that it is important to make both the renderer and the JIT essential services of an OS. Using java shows how heavyweight it is to startup a such a compiler just for a single little application. Similar effects can be noticed when starting up all the different browser you have installed (especially, as many of them are not only html renderer but also JIT compilers for JavaScripte etc.). Furthermore, all this sandboxing and protection that modern browser do, they often tend to double functionality that is provided by the OS anyway.

What does this mean for the OS: looking at the JIT aspects maybe it is time to make Singularity (One of my favorite papers – or better series of papers) or Java OS reality. From the html renderer perspective, I believe chrome OS is on a good may, they just have to hop more on the App concept and leave the browser behind.

Commonly, I use London, Amsterdam, or Frankfurt as hub when flying to the US. This time I was booked on Swiss and changed planes in Zurich (Stockholm-> Zurich –> San Francisco). It was my first time connecting in Zurich and I have to admit that I was a bit nervous: I was scheduled for to have only one hour to change planes in Zurich. Based on my experience from major hubs I was not expecting that I could make it on time to my flight to the US.

And then the plane even was delayed 10 minutes when we arrived in Zurich…

But, somehow, everything went smooth: short queues, quick but precise security checks, and I nicely boarded 15 minutes before takeoff (what seems to be normal in Zurich). That is nice! Service is great with Swiss as always, just the screens are not really not good (at least mine).

So, I finally found some time to watch the “Social Network” Movie. Now, I like it, but they really make him look like an idiot. I am not sure if he deserves this.

P.S. Matt Welsh: I do not like your the way they dressed you in the movie. And I hope that you have had a couple of more people in your class, at least in the undergrad ones.

A little HowTo on running TinyOS applications in the Cooja emulation / simulation environment.

  1. Cooja is included in the Contiki CVS Git. Hence, make sure you have a recent cvs checkout git clone / checkout / branch /… of Contiki on your system. See http://www.sics.se/contiki/download.html for installation instructions.
    2011-03-27: update: contiki is now on Git.
  2. Compile your tinyos application with “make telosb”
  3. In your Contiki installation, go to tools/cooja/ and run “ant”. This requires you to have java and ant installed. After compilation it will greet you with an empty simulation environment.
    cooja1
  4. Hit File –> New Simulation to configure your simulation run.
    cooja2
  5. Press create and you will see your initial setup.
    cooja3
  6. Now it is time to add some sensor nodes. Hit mote types –> create mote type –> sky mote type and select the image (main.exe) of your tinyos application by hitting browse.
    cooja4
    cooja5
  7. Hit open and create and next specify the number of sensor nodes you need with that application image. You can add other application by repeating the steps 6 and 7. Hit create and add to make the sensor nodes appear.
    cooja6cooja7
  8. Play with select visualizer skins to customize the sensor visualizations. I prefer mote ids, leds, and radio traffic.
    cooja8
  9. Activate the radio logger (Plugins –> radio logger) and place all windows conveniently on the screen.
    cooja9
  10. Press start to see the action. Check the timeline to see packets sent and received and also the Leds. Check the loggers to see radio packets and serial communication.
    cooja10
  11. Cooja has many other features such as serial sockets, debugging, etc. I will leave it to you to explore them. Please keep in mind that some functionality in Cooja is specific for Contiki and will not work (or only partially) with TinyOS.