Writing documentation is so much fun.
Though we all always aim to write code that clearly communicates the ideas and intentions of our code, there are still moments where we need to write documentation and describe something to our colleagues. And when we need to do that, what programs should we use so that also our colleagues could update the documentation and the living nature of documentation would be fulfilled?
What has worked in some projects for me, has been the combination of PlantUML and Markdown — with a dash of integration into IDE and maven plugin or a hint of Python script to do transformations into HTML.
PlantUML is extremely unsexy project to provide capability to define UML graphs in text and create pictures from them automatically.
A cool sequence graph like this:
Could be created with a text like below:
@startuml
actor serviceperson
boundary Siebel
participant Cognos
participant MessageBroker
participant "Alfresco Api"
participant Portal
actor Customer
title Sequence diagram describing how different actors interact in Service Report-integration
serviceperson -> Siebel : register report
Cognos -> Siebel : analyse data
Cognos -> Cognos : launch report generation, \n generate files to disk
MessageBroker -> Cognos : Read metadata and files
MessageBroker -> MessageBroker: Transform message
MessageBroker -> "Alfresco Api" : post the file and metadata
"Alfresco Api" -> MessageBroker : respond OK or error \n create new file or \n replace existing file
Portal -> "Alfresco Api" : Search reports
"Alfresco Api" -> Portal : Response listing\n with download links
Portal -> Customer : Present listings
Customer -> Portal : Request download
Portal -> "Alfresco Api": Download file
Portal -> Customer: Stream file to user
@enduml
Fast to write. Fast to understand.
Drive the point home better than with a longer prose or ASCII graphs.
Then what about Markdown? How does that fit into the picture?
Markdown syntax allows you to create really quick formatting to your text and transform that to HTML later on. Once again makes you a bit more agile in writing your thoughts down and describing them to your colleagues.
And the good part?
Most likely your IDE or editor already has some kind of support for these syntaxes, making your work and workflow even more smoother — allowing you to preview your graphs and documents fast.
Above examples show plugins in IntelliJ Idea.
Otherwise depending on your workflow you could integrate graph generation and markdown transformation into a maven phase — or do like I do, use Python script to manually generate html versions when needed.
#!/usr/bin/env python
#
# This script transforms markdown and plantuml documents into html-files and png-images
#
# Transformed images are put into html subdirectory
#
import os, sys
from fnmatch import fnmatch
def ensure_dir(f):
d = os.path.dirname(f)
if not os.path.exists(d):
os.makedirs(d)
if len(sys.argv) != 3:
print "Usage:", sys.argv[0], "" , " plantuml.jar path>"
sys.exit()
directory = sys.argv[1]
plantuml = sys.argv[2]
for path, directory, files in os.walk(directory):
for file in files:
if fnmatch(file, "*.md"):
markdown_file = "%s/%s" % (path, file)
html_dir = "%s/%s" % (path, 'html/')
ensure_dir(html_dir)
html_file = "%s%s" % (html_dir, file.replace(".md", ".html"))
os.system("markdown2 %s > %s" % (markdown_file, html_file))
if fnmatch(file, "*.puml"):
puml_file = "%s/%s" % (path, file)
print puml_file
os.system("java -jar %s %s -o html" % (plantuml, puml_file))
Above Python script traverses directory tree you give it to find Markdown files ( *.md ) and PlantUml files ( *.puml ) and creates html subdirectories into directories to store html versions of the text and png versions of graphs.
As a second parameter script requires path to plantuml.jar.
Script should be easy to understand and modify to your own needs.
With Markdown and PlantUml integrated into your coding workflow there should not be any more reasons not to write necessary documentation for your colleagues. And as everything is text based and tightly integrated into the build system & environment – anyone can update, fix and improve that documentation at the same time as they update or refactor the code.
Huima 