Application Development Blog Posts
Learn and share on deeper, cross technology development topics such as integration and connectivity, automation, cloud extensibility, developing at scale, and security.
cancel
Showing results for 
Search instead for 
Did you mean: 
Former Member

I've been developing ABAP code for over 7 years now, and it amazes me how much time is lost creating documentations worth nothing. Most times projects don't know how to properly document their source-codes. They require you use ugly templates with tons of information that get's old as soon as they are typed in the word document. A lot of time and money wasted, writing something nobody will ever use.

Well, that's enough for my rant :smile: . I already wrote a huge rant about documentation in another blog. This is just to give you a little background on why I started looking for alternatives. This year my professional life turned upside-down due to a lot of reasons, but in the end I was lucky enough to stay in a team where we can use whatever tool we judge is best to get the task done. And that's how I find ASCIIDOC.


--------------------------------------------

ASCIIDOC?

ASCIIDOC is a small and free tool created in python. Basically it's a script that can read a source text file written in a particular way, and generate a cool output in a variety of formats. You can create HTML, PDF and even ePUB files (some of them use DocBook as a base for conversion). You can also specify a .CSS file as a template.

ASCIIDOC's homepage has a huge and detalied documentation with everything this small tool can do. You can get an overview clicking here.

Small Example

In the past, everytime I started writing a technical document I always thought that I wanted to keep it as simple as possible. I don't need tons of fancy stuff (hate those crazy templates), what I need is a fast way to explain how my application works.

If you're into pc/console gaming, odds are you know well an website called GameFAQs.com . It has tons of Walkthroughs, Charts and Guides for a HUGE amount of games. Check out these guides, for Castlevania: Symphony of The Night (one of my favorites of all times). That's almost exactly what I always wanted for my coding documentation: relevant information in small and simple files.

Let's see what we can do with ASCIIDOC. After you've installed the tool, copy the contents of this web page to a new text file. Then open the command line at the folder you saved the file, and run asciidoc <filename>.

This command will give you this output. Cool isn't it? :grin:

At the top of the text file, there are some words with two ":" in it, like :toc2: . Some are backend attributes, that you can specify either in the file or at the command line (e.g. :toc2: wich creates the table of contents would be asciidoc -a toc2 <textfile> in the command line ).  The other ones are "variables": I can change the value for :myemail: only once at the top, and every place in the document where I used {myemail} would also get changed.

Creating topics is really easy, you just have to underline the title according to the sequence: "==" is the document title, "---" is the main topic and "~~" is for the sub-topics. There are tons of options, like tables, links, images, thumbnails, cross references, bulleted lists and so on. Checkout the ASCIIDOC Cheatsheet for a list that covers the most used commands.

Usage

First of all, once you create your own .css file documents get a very "professional style", but are still lightweight files. I've created a template for my company and it works great.  I can also create a .pdf and send to my clients, or keep the .HTML on our server for a fast and nice way of checking the documentation.

I'm finding it really easy to maintain the documentation files, because ASCIIDOC uses a very intuitive formatting. In addition to an enhanced text file editor, like Sublime Text 2, it's even easier (there's a plugin for ASCIIDOC format highlighting). It's simple and fast to deliver new documents as I don't have to care about templates and such, just format the information in a way it's easy to read and it's good to go.

Your going to use the command line a lot with ASCIIDOC, so it's propably not the best tool for end users. But hey, you can always create some shell scripts or batch files (which I used a LOT when creating my own .css template).

Alternatives

I know ASCIIDOC may not suit everyone needs. So I'm guessing some of you may also have cool alternatives to software documentation. Hopefully you'll share those hidden gems with us on the commentaries. :grin:

--------------------------------------------

Thank you and see you next time!

5 Comments