A walkthrough to demonstrate capabilities of walkthrough.so

This is a demo walkthrough to showcase the capabilities of Walkthrough. But before we go, we want to briefly talk about why we need walkthrough in first place.

For last 5+ years, I worked as a platform engineer at Uber. During this period, Uber was in its rocket ship phase. To put in numbers, I joined as ~3000th employee in 2015 and there were 26000+ employees when I left. 

As a platform engineer, I was responsible for building the core logistic platform on which every trip for every business line of Uber happened. We were a small team of ~50+ engineers owning over 100+ key integration points across 10s of microservices. We were supporting 2000+ internal engineers to use our platform. We used all different tools - wikis, docs, API docs etc. To scale better, we wrote tutorials, playbooks, how-tos, guides, runbooks etc. (called practical documentation). 

But even with that “onboarding customers at speed” kind of remained a big challenge. So about a year back, I started building this product.

Top&nbsp; 5 Challenges with Practical Documentation

Most tech platform companies rely on - how-to guides/tutorials/runbooks (a.k.a practical documentation) to write down operational procedures for themselves and their customers. But such documentation often lacks in quality and leads to organisation wide chaos.&nbsp;

Introduction

From my own experiences of technical writing, I decided to create Walkthrough.so

But in broad sense, it is more than that. <b>Walkthrough is a content management system for your organisation's practical knowledge</b>. Its one tool to write and manage your how-tos, tutorials, runbooks and other operating procedures.&nbsp;

Why Walkthrough?

Walkthrough's unique block style editor is built for easier writing. Here are some basic kind of content blocks that you can use.

Walkthrough supports 3 levels of headers with different sizes.

Lists are important for writing smaller line items

To separate out sections in a step, you can use 2 forms of dividers

Basic Components 

To make code writing easy, we have a custom component that supports syntax highlighting for all languages.

This component supports tabs to enable writing multiple languages or write request/response code.

But often, you have code hosted on Github. Its very easy to embed that into your walkthrough

e.g. Just by pasting this <a href="https://github.com/golang/go/blob/master/test/alias.go">link</a>

Code Writing

To explain things better to your readers, Walkthrough supports a few more interesting components.

There are different colors for Error, Warning etc.

Sometimes, it is much easier to explain verbally. Not everything is worth to be written down. e.g.

Explaining better

Most technical writing involves screenshots/architecture or flow diagrams. So we make it easy to save images in Walkthrough.

You can simple Ctrl + C/Copy an image into this document. Behind the scene, Walkthrough takes care of uploading it to cloud and then also storing it in CDN for faster serving later.

Videos can be simple put by putting URLs from popular video hosting services like Youtube/Vimeo.<br><br>e.g.

Images and Videos

Technical content often includes links to different tools/content. There are 3 ways you can display links depending on use case.&nbsp;

e.g. To ask user to do something in AWS console, you can create a button&nbsp; -

Links and Actions

Often you have some scripts or other types of files like pdfs, zips that you want to share with readers.&nbsp;

Walkthrough makes it very easy to host and share such content.

editable-react-table-master.zip

Attachments

Technical documentation often requires readers to run commands by replacing some parameter in the commands with their own ids.&nbsp;

To get pods in kubernetes cluster, use below command by replacing <code class="inline-code">YOUR_NAMESPACE</code>

But if is required to be done many times, it gets repetitive and error prone. So same thing can be done better with Macro.

This renders the macro in the form of question and the answer will be set into the macro variable and applied to your content.

Macros

In this walkthrough, we have shown the power of this platform.&nbsp; We have been adding more and more capabilities to walkthrough.

Walkthrough of Walkthrough

Nilesh Mahajan