First steps to success!

I was thinking, how come I have no completed hobby projects? I couldn't find a reason, so I concluded that perhaps I'm too stupid to complete anything. Then I open Visual Studio again and started thinking what other features I might need in my utility library... Then it struck me! I haven't completed anything, because none of my hobby projects had requirements or design documents (which, IMHO, is the same thing)! So, I decided, that I will never write a single line of code, without having requirements or design documentation written.

I was very happy and excited, but then I've come to another problem. What document format to use for the documentation? Being an inch smarter than I was five minutes ago, I decided to gather the requirements for the document format, and then try to find one that matches as many as possible of those requirements. So, I fired up my good friend Notepad++ and started typing...

Here are the most important requirements:

  • Version control system friendly or in other words - it must be a text based format, I must be able to diff two versions of the document and so on.
  • If the format isn't easily editable by hand - it must have at least one free editor. Note that WYSIWYG editor is not required.
  • IT must be easy to separate content from presentation.
  • The format must support embeddable elements (and they must be easily editable/replaceable):
    • Tables;
    • Images;
    • Diagrams (this one is optional, because I can embed images).
I immediately knew, that what I'm describing is HTML (or XHTML). After some googling, I also found DocBook, and some more XML-based formats. I liked none of them! XML is a horrible language to edit by hand (you have to remember to close the tags, you have to replace some characters with their codes etc.)

Then, while reading something about DocBook, I saw LaTeX being mentioned. I looked at it... And I couldn't believe I wasn't using it already! It's my kind of way to create documents. I mean, how often can you tell someone, that you're compiling your documents? :)

And besides, LaTeX meets all of my requirements. Text based, free editors (any text editor, or something more WYSIWYG-ish like LyX or TeXnic can be used), content separation from the presentation is probably the main philosofy of all TeX formats, through some external packages LaTeX let's you embed almost anything.

So now, I have MiKTeX, and I'm experimenting with document classes and packages. I will probably create my own classes, because I want to have the common look and feel.

If you're a programmer like me - have a look at LaTeX! It's brilliant!

Subversion and Vault (again)

Ok, the two readers that I have might think I'm crazy or something. But I'm starting to dislike Vault again. I know, I know... This time, it's the "Add solution to Vault" thing that got me on the edge.

In subversion, if you need to add a new project or a solution - you simply check-out the directory that will contain this project or solution. You copy the directory of the project or solution in there with all of it's sub-directories. You do a few svn add -N commands and a few svn propset or svn porpedit commands (to set the correct svn:ignore's and, possibly, other properties - like mime-type etc.) and then you commit the changes. That's it!

In Vault, however, this is much easier. Ahem. You just start the Vault client... You wait for the client to start... For about 2 minutes... You right click on the directory that will contain the project and choose Add Files/Folders, now you just navigate to the right directory, select it, select the right files and click on the OK button. Now, you wait... Wait and pray, because 90% of the times, Vault will fail with some very unclear error message...

So, the task of importing one solution with a few projects into the repository - the task that would take no more than 5 minutes on subversion - it takes 2 to 4 hours on Vault... Well, if I had to do this again on Vault, I wouldn't even bother to do it this way. Now I know, that the best method is by creating a fresh solution in Visual Studio, importing that empty solution into Vault, and then just adding projects and files into it. I wish I knew this before, though.

I don't know... How many more times does Vault have to disappoint me and my colleagues, before we will switch to subversion?

Python 3.0 is finally out!

Finally, we have Python 3.0! I wonder, when will the IronPython catch up with the changes...

Btw, I was looking at NSIS the other day and I started wondering - why aren't there any install systems, that would use python as their scripting languages? I mean, this would give the power of python for the install script (classes, functions, standard library) and it would still be able to generate a native executable file (py2exe anyone?) - the setup program. Also, python is portable - it shouldn't be hard to port this kind of install system to other platforms!