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!

No comments: