Edit Text-files offline

The system I’m using for this piece (RubLog) is somewhat of a compromise. I write the article offline, using whatever text-editor I prefer, can commit the text to CVS (a version management system) if I desire, and let RubLog publish it directly from CVS. The advantage being, I can edit it wherever I am with my laptop and the text-file is accesible to any tools I might have on my laptop, such as a spelling checker if I’m not too lazy to use one. The other side of the coin is, if I spot an error in the text while reading the web-site, I cannot directly correct it, but have to go back to the text-editor to modify it and commit the new version to CVS.

Edit text-files and document objects online

Other systems, such as ZWiki and Itor (on which I’m programming myself) accept changes only through a web-browser. This makes it relatively straight-forward to correct typos - just open the web-page that needs to be changed, click ‘edit’ and presto… I can make my change directly, and version management (if any) is handled for me by the system. Click ‘save’ and I can see what the page now looks like. Not exactly WYSIWYG, but it provides me with fairly rapid feedback. This coin also has a flip-side: I have to be online to edit the text, and am constrained in editing possibilities by the simple text-boxes web-browsers offer.

Use a word-processor

One nagging thing RubLog, Itor and Zope have in common, is they are not fully WYSIWIG like my word-processor is. If I want to get an idea down fast, including pictures, I grab Open-Office Writer and Open-Office Draw. I can simply add titles, quickly create drawings, and include the drawings in the article. While I do that, I see what I am doing, because Open-Office is WYSIWYG, and does not need a separate rendering step after creating something. I currently like to write articles around a DiagramOfEffects (DOE). I usually start with a diagram, and describe that in the article. As the writing progresses, the diagram evolves. With a word-processor, I can add and modify diagrams rapidly. For a web-site, I’ll have to manually render the diagram to a bitmap. For every change to the diagram, rendering is required. Needless to say, I won’t start such an article with any of the text-based systems.

Another disadvantage of starting off the web, is that printing web-pages is still a nightmare, as I recently re-discovered when we tried to print registration forms for xp-day_benelux. So for readers who’d like a hardcopy, I’ll have to create a PDF from a separate document. Now I have two different articles… I’m unlikely to do this, If I ever intend to change anything to either of these articles.

render the word-processor text to HTML and PDF…

Now for the flip-side.… Although writing and drawing with OpenOffice is easy, rendering for the web leaves something to be desired. The easiest thing to do, is convert the document to PDF tm (PortableDocumentFormat) and upload it to the site. Most people have a PDF reader, and many search-engines index it. The advantage of this approach is, that it’s fast and easy :just choose ‘print to PDF’ when using OpenOffice in combination with Linux, it’s easily printable (unlike web-pages) for readers and the layout as written is preserved. The disadvantage is, that it isn’t a web-page, so it doesn’t integrate with the remainder of a web-site and doesn’t lend itself well to using hyperlinks. OpenOffice does render to HTML, but creates HTML with a horrible layout and duplicated style and font tags for every paragraph. The WYSIWIG nature applies to printed documents… Carefully added whitespace to put a diagram at the top of a paper-page leaves empty spaces that look ugly on a web-page. Specifying exact fonts to be used is inconvenient, as the web-site containing the document has to specify the style…

Where does this lead?

So for now, I guess I’ll continue to compromise. Write short rants like these with a text-based system, and write longer articles with pictures with OpenOffice, which I subsequently covert to HTML if I’m not too lazy.

That’s what I thought…

After writing this rant, I thought it’s time to get my act together and make my favourite way of writing articles of a few pages with pictures more comfortable for myself. This resulted in a simple program to remove extranous tags such as <FONT> from the html generated by OpenOfice . See TagCleaner for the result.

This week, I stumbled across bugmenot, where people can share logins for all kinds of sites. E.g. this one for soundclick, an online music site. I like to listen to fellow amateur composers, but I categorically refuse to register for these sites. There are too many, and i don't see what value registering provides me...

Unlike some other sites of course, where registering does provide value. For instance, forums such as synthforum.nl where registration makes it easy to follow who says what. bugmenot allows me to decide when I find it valuable enough to register, and when not.

I did not necessarily agree with his views or the way he treated other people, I do however appreciate his ongoing efforts to stir up dialogue and debate about issues in our society. If someone feels attacked, use a pen or the law to react, not a gun...

Here you can find my ruminations on (agile) software development practice, systems thinking, as well as rants against ‘the hype du jour’ and sometimes system administration tips. I call it a ‘column’ as that is what this form has been called by (dutch) newspapers for a long time. On the web, it is hyped as ‘new’ and is often called a blog.

You can find contact details and more information on my professional activities at www.willemvandenende.com .

About the software serving this column

This site is running on a combination of Apache and RubLog, a piece of software created by Dave Thomas. If you want to use this software, you can download the source code and installation instructions from rubyforge RubLog is a simple file-based web log/wiki. It has a few distinguishing features:

• It accepts input in a variety of markup formats. HTML, plain text, and RDoc formats are supplied by default, along with a handler for Usemod wikis. More can be added without much effort (this file is in RDoc format)
• It works from conventional files and from CVS/RCS repositories. This is useful is multiple people are using the same blog: have them check stuff into CVS, and point the blog software at the repository.
• It supports category-based and time-based access (and combinations of the two).
• Output styles are pluggable: a standard example and a style to support printable documents are provided.
• It supports WikiWord-style links between articles (in RDoc mode).

RDoc License

RDoc is Copyright © 2003 Dave Thomas. It is released under the same terms as Ruby.

They distrust spontaneity because it threatens the perfection of their formula for how things should be. It's one example of the reverence for the abstract and the material, over the relationship and the people (more on this soon). It leads to the deadening formulaic "have a nice day" customer service instead of allowing human beings the possibility of creating some fun together in a way that works for them in the moment.

If you follow the first road, you could get some living software, that lasts a long time, because the users get to live in the software, and become inhabitants, rather than just users. If the inhabitants really feel they have an influence of where the software is going, you might get viral marketing. This approach is scary, since it forces the product developer to relinquish some control over the product to the inhabitants.

The second approach doesn't prevent success: the pre-defined vision doesn't change much, so it is probably easier to create pre-defined marketing material for it. If the formula doesn't stick, you're in trouble though. You also risk continuing friction between your vision and that of the users.

In complex situations, such as software projects and the teams that work on them, there's never such a thing as "the problem". The sense that something is wrong may be the start of a break with routine - the start of a problem-solving process.

From the list, I prefer to reinforce what works, to compensate for natural tendencies to think in negative ways about problems.

Another favourite of mine (although I'm not quite sure if it fits in Laurent's list), is Reframing - taking a different perspective so the problems at hand disappear and the situation looks entirely different. Marc Evers pointed me to a blog entry by Ton Zijlstra about information overload, Every Signal starts out as Noise which contains this example:

there is no such thing as information overload. It does not exist.

When trains were first introduced passengers suffered from jet-lag like symptoms, even at speeds as low as 20 km/h. Most likely because for the first time sensory input became asynchronous. What you heard and smelled (the train, people in the car with you) did not coincide with what you saw (the landscape passing by). We adapted, we have to do so now.

individuals and interactions over processes and tools

In the nineties, I used to be fond of CASE tools and the like, and wonder how to put an iterative planning in MS Project... Over the years, my preference has shifted more and more to individuals and interactions, as I have seen no evidence of higher productivity through CASE tools or software planning tools, but have experienced firsthand the enormous power of simple face to face planning and design meetings, with open communication and simple tools such as index cards, whiteboards and physical planning boards.

Rachel Davies just wrote a piece on using index cards with five reasons to prefer index cards over an online story repository, and five reasons for exactly the opposite. The quote below stresses to me the importance of looking for the root cause behind the wish to use electronic story repositories as a solution:

When making a choice in what medium your team uses for stories consider this:

• index cards support more extreme behaviours - sitting together and customer conversations
• use of electronic tools may be used to support larger teams with a customer who may be off-site. They may appear more effective for larger organisations but their use may mean that issues of team size and location are not challenged.

On the collaborative design side, someone asked me recently which code-generating UML (Unified Modeling Language) tool I would recommend. This is a simple question that gives me enormous difficulty in answering. I have studied CASE tools and the UML intensively in the past, and since I saw no benefits delivered, I lost interest about five years ago. Since I lost interest, I have not kept up to date, I have a nagging little feeling I might have missed something. But the feeling remains little - I have not heard overwelming success stories. Maybe I'll go into some of the reasons I lost interest:

• UML was not computationally complete, so creating executable models which was the pipe-dream of CASE tool builders would remain exactly that. Computer programs are already executable models, and while creating (by necessity more) abstract graphical representations of the program can be useful for understanding, creating a program from the diagram alone was not an option. That doesn't mean I find graphical notations useless for performing programming-like activities with a computer - only that the UML is not a suitable notation for doing so. I think it works better within a reduced scope, such as e.g. a modular software synthesizer like Reaktor which I enjoy using.
• UML tried to include everything and the kitchen sink, and from version 1.0 onwards, it became only more elaborate. Trying to think about a design with dynamic models hrough UML made my head spin, and gives a team an extra chance to get stuck in analysis paralysis, e.g. by deciding which of the bewildering amount of notations to use, and determining exactly what the sementics are of a particular bubble or square...
• With respect to CASE tools, Round-trip engineering (going from diagrams to code and back iteratively) is probably still difficult, although I heard poseidon does a reasonable job.
• Using case tools takes a lot of work and wasteful steps. I remember trying to use Rational Rose, which had a dialog for creating a class with like twenty tabs...

That is not to say, there is no value in the UML at all, I just value brainstorming with colleagues more... I use UML sparely. Mainly informally with a team, gathered around a whiteboard or a table with index cards (of which we take photographs afterwards, if anyone wishes to keep the diagrams) solving a particular problem.

In case you might need to create a more formalised view of your diagrams. Martin Fowler just put up a list of uml sketching tools, I used to use the visio templates he mentions as well, and they worked pretty well.