Rethinking technical writing. Can Poet provide a better experience? | Poet

Less is more

I think writing, and teaching in general, is a form of art. And as such you need a proper place to do it. Where you write matters. I prefer to write my articles and books in an editor that has minimalistic user interface. As less icons, bars and menus as better. The zen mode of Code for example brings that minimalism to my screen. I am also very often coding in that mode with just two, three files opened at a time. This makes me focus on what currently matters - my task, the source code and how to solve the first one with minimum changes on the second one. This involves a little bit of logical thinking, knowing the domain, having the right context. Not necessary inspiration. Writing articles or books on programming is quite different though. I do need inspiration to write. And that inspiration sometimes stays alive because of the environment. My first two books were written in Microsoft Word. I will admit that it wasn't the best experience ever. There are so many distracting things in there. A set of bars at the top, status bar at the bottom, rules around the paper and couple of menus on the right side with options for fonts and formatting. I hated it but that is what the publisher wanted and I respected that because I knew the reasons. My third book though was self-published and I had all the freedom to write wherever I want. I picked my favorite editor together with my favorite language - Code + markdown. The whole process was completely different. I was writing fast and straight to the point. I felt better and the words were coming easier. I had this in mind when started developing Poet.

From the very beginning I wanted to design something that is close to these ideas. And I believe that Poet is kind of that thing. Look at the following screenshot. The article that you are reading now is written in Poet and that is how my writing experience looked like.

The markdown editor on the let side and a live preview on the right. The preview is also important because I can spot issues right away while I'm writing. What I was doing so far was jumping between Code and the browser. This became a problem especially when I had a lot of text, code, diagrams or pictures. Visual Studio Code itself has a good markdown preview but the overall shape of the article is different at the end because I have different styling on my blog. The preview of the editor here is exactly what I am going to see at the end.

Poet actually has a customizable layout. Sometimes I need more tools sometimes I need less. The layout manager is flexible enough so I can arrange the positions of the panels and then later use the gutters between them to control the size. The following layout for example

produces a screen with all the panels:

JavaScript editor, HTML sandbox, console logger, Story panel and Story preview.

Exercising the code

If you ever written a technical material I bet you tested your code locally or at some online playground like Codepen or Codesandbox. And that's quite important for two reasons. First, you want to give the opportunity for the readers to try out what you are talking about. And second, you don't want to post something that doesn work. Poet provides similar capabilities. You can create a fully working app. And of course share it afterwards. For example, the following is a React hooks example.

(Change the code and save your changes by hitting Cmd+S or Ctrl+S)

The code that I used to add this here is as follows:

<iframe src="https://poet.codes/e/JEXxBxzk1TM" style="display: block; width:100%; height: 600px; border:0; overflow:hidden;" sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin allow-top-navigation-by-user-activation"></iframe>

In terms of external dependencies Poet works with everything that is distributed as UMD build. Or in other words if you are able to get something over http it will work in Poet.

Technical writing done right

If you open some of my first blog posts you will see something which is typical for every beginner writer on technical topics. That is when you have the code in your head and an idea of what you want to say but you are wordless. Over the years I learned that showing the final code/result is not enough. It is actually a lot more interesting how you reached that point. Your path is more valuable because it illustrates how you think and how you approach the obstacles on the way. Also your reasonings may be different from the ones of the reader which makes your solution invalid for them.

I appreciate when the author starts with something small and build on top of it showing the big picture. I always struggle doing this because I usually have no history of my progress. When I learned about version control the things changed a little bit but till today there is lack of tools in that direction. An instrument that supports the writer during the process. Git is pretty good at keeping track of changes but it is source code oriented.

What I am usually doing is committing my changes as often as possible. When I am done with the code and start writing the article I come back to the Git's log to figure out how the things happened.

I'd thought that it will be nice to get all of my commits and use them to write my articles. I cherry pick the meaningful ones and write content next to them. Then the reader will see exactly what I did and why. And that is how Poet was born.

To give you a little bit more context, let's say that we want to explain how to bundle JavaScript with browserify. We could easily write two sentences saying:

Install browserify with npm install browserify.

and

Then run browserify entrypoint.js > bundle.js

And we are done right. Well, it will be much better if we show couple of files and explain why they need to be bundled. Then we introduce browserify and say that it may be used from the terminal but also from a regular server-side JavaScript. At the end when the commands produce the desired bundle we give a raw overview of how that tool stores our files and how it resolves dependencies. That sounds a lot more interesting and valuable right. I clearly remember how I did it here. I created a dummy folder locally and started playing with some code. At the same time I started filling a dedicated post.md file which later became an article on my blog. I also remember that I changed the direction of the article serveral times and so the example on my machine. I had a hard time syncing post.md with my code locally.

Today when Poet is around I am following a different approach. I write my example at the same time while I am writing my article. For example I am writing some code and when I am happy with what I see I commit it.

Then I move forward with more code and so on. Every time when I introduce something new to the reader I am making a new commit.

At the end I instruct Poet which of my commits go into the final Story. What gets published as a page on Poet is my commits or to be more specific the markdown messages.

Poet allows me to make changes to both code and text and keep them in sync all the time. I may build on top of what I have and create a new commit with a new text explaining what I am doing. It is like Git, CodePen and Medium in one place.

Here is a Story where I explained how to build a simple JavaScript template engine in 20 lines of code. Click over the commits on the right and you will see how I progress towards to reach the final solution.

Also follow this link to see how the final Story looks like.

The devil is in the detail

There are couple of things that bothers me while blogging. I always have to copy code from where I exercise my example to where I write the article. This involves switching between the browser and the editor all the time. In Poet, because the code and the text are tightly connected, this is no longer needed. Look at the following gif. While I am writing I can quickly select some of the code and see it in place with no manual copy/paste operations.

And if we have to continue the work in this Story (understand explaining the various parts of the CSS rule) we will need to talk about body, margin and 2em. We will probably end up with something like this:

Now this is interesting because here we split a little bit. We are showing the code and a text which is describing it. However, they are not really connected and if the snippet is sligtly more complicated/longer we will have to refer to it all the time. At least that is what I am doing as a reader now - I see the implementation and I start reading the explanation. To fully understand it though I have to constantly jump between the code and the text.

I decided to address that problem in Poet with something which I call annotation. Here is how it works - we create a markdown link and on the place of the URL we go and select part of the code. Poet injects the filename and meta data for the selection (line and cursor position). Then later when rendering the Story it draws a line between the code snippet and the text. That line is visible when reading the text and mouse over the link but also when scanning the snippet.

I have made an experiment and plagiarize a part of Dan Abramov's blog post Why Isn’t X a Hook?. I focused on the following section:

Try reading the text below the snippet. When you reach theme.comment is it easy to find it straight away. What about theme or useTheme(). And this is just 20 lines of code. What if you have 40 or more. Here is how this same section looks like in Poet:

(Go here to see it in action)

Another problem that I have often is the fact that I have to show a diagram. Many times I draw stuff with text but that doesn't look good. At the end I open Photoshop or similar tool and paint something sensible. Like this one for example:

graph LR Browser-- request <br />to the server ---Server Server-->C[Database] Server-->D(Third party);

This time though I didn't use anything else than Poet. It has Mermaid integrated and we can write our diagrams directly as markdown. For example the graph that you see here is produced by:


```diagram
graph LR
  Browser-- request 
to the server ---Server
  Server-->C[Database]
  Server-->D(Third party);
```

The bit which is missing right now is support of direct image upload. This needs a lot more work and planning. Probably even a budget. For now I am uploading my images to S3 which is a nice solution for such things.

You are not tight to Poet

My goal with Poet is not to make it dominant place for technical writings. If that happens I will be more then happy but what I want is to have a better experience while writing. And eventually a better experience while reading. If you for example already have your own blog and you don't want to see your stuff published at poet.codes you can still use it. By default everything that you create is hidden and visible only for you. When you are done you can get your material in a JSON, markdown or HTML format. For example this same article that you are reading now is available here as a Poet Story page but also at .../5lOM3epvZtB/story.json, .../5lOM3epvZtB/story.md and .../5lOM3epvZtB/story.html. The JSON and HTML may not be so helpful but the markdown endpoint should be enough for you to transfer your work in another place and publish it there.

Call for writers

I am really keen to see someone testing Poet. I mean actually writing something and letting me know how was the overall feeling. If you do it go here, post your opinion or find me in Twitter. I would love to hear what you are thinking.