I’ve started working on documenting our application. So I need to take screenshots of the windows, add them to a document, and write up what each window does. A useful and necessary part of that is a fast tool that lets me annotate an image with arrows and text. Maybe some rectangles. But nothing sophisticated.
The critical aspect is that you never get it right the first time. Or you change the layout of the application window and you need to redo the documentation. If you have to redo all the markup every time the layout changes, you are dead.
So what tool lets you open an image, create a new layer, add text and arrows to the layer, then save the document keep the layers separate so that you can replace the old image with a new image down the road? You also want to be able to select that text, change it and move it, and re-align the arrows.
Tools I considered:
- Gimp
- ShareX
- Paint.net
- Inkscape
The tool has to be obvious, because I might go away a year before I come back and have to work on it again. I am going to forget how to do it.
-
Anyone who has tried to add a rectangle in gimp runs into a WTF: Why is it so difficult and non-obvious? There is no tool to “create a rectangle”. Instead you have to “select a rectangle” then “Fill selection outline”. I’ll never remember that. And it is hard too. Google how to add arrow plugins. I can do all that but it will take me hours to recall all the nuances. Sorry, I gave up after a few hours of crappy results.
-
ShareX is fast and has excellent basic tools to do what I need. Unfortunately, once you save the file, all the work is lost. No layers. No way.
-
Paint.net is excellent and fast. The only weakness is that objects are blended into the image as soon as you hit Enter. So you need lots of layers and will have to redo each layer when you re-edit. Doable.
-
Inkspace does the job properly. Not trivial, and I am going to have trouble remembering how to get back to it (hence this post). But it has layers and keeps everything as Objects.
I’ll get better but here are the basics:
- Start by importing an image. You can link or embed. Choose embed. Go to Document Properties and select “Resize to Content”.
- Create a single bezier curve with an arrow. Create some text. Make sure they are the same color.
- It is faster to copy and paste existing text and arrows than it is to get all the settings right over and over. If there is a way to make these values, I have yet to learn.
-
Once you copy and paste the new values, editing is weird.
a. For the Text, type the letter “T”. Then click on the text object. Then type new text.
b. For the arrow, type the key “F2”. That puts it into an edit mode where you can click and move the start and end points.
For assembling the document and building the html (or pdf), I am using asciidoctor. I could not get the Eclipse plugin to manage complex nested documents. VS Code or IntelliJ-Community works ok.
