Templates released

1 files changed, 180 insertions, 0 deletions

diff --git a/content/posts/templates-released.md b/content/posts/templates-released.md
new file mode 100644
index 0000000..f1e6a94
--- /dev/null
+++ b/content/posts/templates-released.md
@@ -0,0 +1,180 @@
+Title: Let's document
+Date: 2019-02-01
+Category:
+Tags:
+Slug: templates-released
+Lang: en
+Summary:
+    ElenQ Technology document templates released, with a long writeup
+    about the workflow we use with them.
+
+At [ElenQ Technology][elenq] I just released my documentation templates tool.
+You can find it in the link below:
+
+[https://gitlab.com/ElenQ/templates](https://gitlab.com/ElenQ/templates)
+
+I think that project, even if it's quite simple, it's a really good reason to
+talk about document edition and my workflow.
+
+## The story
+
+As part of my job at ElenQ Technology I document a lot of things: I have to
+make reports, proposals, documentation for projects, notes for courses...
+
+I have to write **a lot**.
+
+If I could decide, I'd share all my documentation and files in plain text. But
+I don't decide, so I **need** to send PDF files and they need to have a nice
+look so the clients understand I take care of my stuff.  I also like to pay
+attention to the aesthetics of what I do so I really like to keep everything in
+order.
+
+That's really difficult to do. Even more if you work with tools like
+LibreOffice that have tons of options and menus and are sometimes difficult to
+understand or hard to make them do exactly what you want. I have nothing
+against LibreOffice but some years ago I realized it's not a tool for me.
+WYSIWYG[^1] tools like that have some characteristics that don't fit my
+workflow well. Let me break them down:
+
+- They are designed to work with a mouse, and I avoid using the mouse because
+  it makes my wrist and arm hurt. That's why I often work with my wacom tablet
+  in mouse-intensive tasks like PCB routing and I use laptop's touchpad in
+  everyday tasks.
+
+- They have tons of menus where you can get lost while the most of the
+  documents you write don't have that kind of complexity. Often, that kind of
+  options just make the documents complex and hard to maintain.
+
+- They don't have a clear separation between the content and the view. When I
+  write I like to focus on the content and avoid to get distracted with how it
+  looks on the screen. I hate "Oh my god, the picture moved and now the whole
+  layout is broken"-like errors.
+
+- Their file formats are difficult to operate with even if they are open
+  standards.  Mixing data with something that comes from a different process is
+  really complex, and it makes the user write everything by hand.  
+  As an example of this: in the previous version of the [ElenQ Documentation
+  Templates][old-version], there was a tool to get all the git tags of the
+  project and insert them as a document changelog. This is really difficult to
+  make in LibreOffice. (This version doesn't support that *yet*).
+
+
+Trying to solve all those issues, I've spent some time with LaTeX as a main
+tool but, it also has a really thin separation between the content and the view
+and its learning curve is crazy hard.
+
+## Enter pandoc
+
+Some day, while working on her PhD, my sister discovered **Pandoc** and our
+life changed.
+
+[Pandoc][pandoc] is a great tool which is able to convert between a lot of
+different document formats. That opens a world of possibilities where you can
+write in a format you like and then convert it to different output formats.
+It's huge. The main power of Pandoc is also related with the amount of output
+formats it can handle. It is possible to write all the content of a document in
+a common language like MarkDown, RST or AsciiDoc and then convert it to
+different output formats like PDF, ePub or to a simple static website.
+
+All this tooling also lets you write files that are easy to write and read,
+like MarkDown is, without the need to play with tons of tags and weird commands
+like HTML or LaTeX do.
+
+Pandoc is a really powerful tool with tons of option that can be quite
+overwhelming. It even lets you add filters that transform the AST it creates
+during the conversion!
+
+At the moment we discovered Pandoc I was really obsessed with productivity and
+the chronic pain my hands, wrists and arms were suffering and I didn't care
+about anything else. If a tool could help me reduce the use of the mouse and
+my keystroke count it was worth the time learning it.
+
+I was so crazy at that time that I made a Vim plugin called
+[droWMark][droWMark] for posting in WordPress. Taking advantage of Pandoc
+filters I also made it able to [upload images][droWMark-images] linked from the
+MarkDown file. It was fun.
+
+## Choose the tools
+
+Some time later I founded ElenQ Technology and I decided we needed to integrate
+Pandoc in our tooling. That's why with my sister's help we created the first
+version of the [documentation templates][old-version].
+
+I wanted any person working with the documents to be able to use the editor
+they like the most. And I only wanted to care about the aspect of the document
+once: during the template creation.
+
+It worked. I spent almost 2 years working with the old version of the templates
+and they served me well. The only problem they had was that they needed many
+files to work and they added some complexity to the folder where the
+documents were edited.
+
+## Choose the tools: remastered
+
+This new version eliminates that complexity. We needed to sacrifice a couple of
+features but now there's no need to add any extra file in the directory where
+the document is. We removed the Makefiles and embedded the SVG logo of the
+company inside the templates using TikZ. Now the tool is just a couple of
+Pandoc LaTeX templates: `elenq-book` template for long documents and
+`elenq-article` for short documents.
+
+Like in the previous version, both templates are designed to create output
+LaTeX files that can be compiled to PDF using XeLaTeX (or let Pandoc do the
+conversion for you). The input formats are not defined, the only limitation is
+on the metadata they need (you can read the documentation included with the
+project for that).
+
+All of this is installed *automagically* using [Stow][stow].
+
+The project also explains in the `README.md` file how to create a couple of
+command line aliases to simplify the calls to Pandoc. You really want to use
+them because Pandoc needs *a lot* of input arguments. Using aliases, the
+conversion as simple as running a command in the terminal:
+
+    ::bash
+    elenqdoc-book document.md -o book.pdf           # For books
+    elenqdoc-artilce document.md -o article.pdf     # For articles
+
+With the new template system, the documents are just Markdown files and they
+are easy to maintain under version control. Note that the same input file can
+be used to create an article and a book, the input doesn't really affect the
+output of the process.
+
+We decided to use MarkDown for some extra reasons too. Markdown is simple but
+has everything that any simple document needs and it's easy to read in plain
+text even for people who don't know it. But not only that, MarkDown is a widely
+use format ([this blog][blog-md] is written in MarkDown too!) and it's really
+extensible, letting the user insert HTML or LaTeX pieces to cover specific
+cases like formulas or complex formatting.
+
+## Choose the tools: future chapters
+
+Next step is the creation of a invoice control system that is integrated with
+the Pandoc templates. The template integration is really easy, we only need to
+inject some variables to the templates and Pandoc already has a tool for that:
+the metadata system. From that side the problem is solved, now we need to make
+all the rest.
+
+On the other hand, as said before, in the future, if the conversion process
+needs extra complexity, we'll just need to add some Pandoc filters to create
+it.
+
+## Wrapping up
+
+In summary, we can say that the tool we made is just a consequence of the
+workflow we follow. This is probably not for anyone, but any person used to
+work with the terminal and software is a potential user for this kind of tool.
+
+It's powerful, simple and straight-to-the-point. I think that fit's our
+workflow really well.
+
+
+[elenq]: https://elenq.tech/
+[pandoc]: https://pandoc.org/
+[droWMark]: https://www.vim.org/scripts/script.php?script_id=5374
+[droWMark-images]: https://github.com/ekaitz-zarraga/droWMark/issues/2
+[old-version]: https://gitlab.com/ElenQ/documentation-templates
+[stow]: https://www.gnu.org/software/stow/manual/stow.html
+[blog-md]: https://gitlab.com/ekaitz-zarraga/personal_blog/raw/master/content/posts/templates-released.md
+
+[^1]: WYSIWYG: What You See Is What You Get