Tuxtorial

anirudh@anirudhsanjeev.orgMarch 11, 2010

0.1 Elevator Pitch

Tuxtorial makes it effortless to create and host high-quality documentation for theLinux Desktop Operating System. A clientside application captures screenshots atkey points of a process, allows the tutorial author to add details and annotate, anduploads to the cloud where everyone can view and improve it.Tuxtorial gives the community great tools to share their knowledge on how touse their computers, and also makes all the information available in an easy-to-usecentralized, semantic, open format.

0.2 Desktop Client

The Tuxtorial desktop client is a native application for the Gnome desktop.

Workflow

Say the user wants to write some documentation on how to create filters for evolu-tion.The author installs Tuxtorial and starts it from the menu. The applicationpresents a simple window with which the author can create a new tutorial or resumework on a saved one. For now, let us consider that the author chooses to create anew tutorial. The application minimizes to the system tray.The user now opens up the application he/she wishes to document and startsperforming the actions that he/she would normally do. At each

key point 

, the userpresses a keystroke, say Winkey + S. When this happens, Tuxtorial silently takes ascreenshot of the desktop. The tutorial can have any number of steps. This processcontinues until the documentation is finished.Now, when the user feels he/she is finished, the tutorial recording can be endedby selecting the Tuxtorial icon from the system tray. This brings up the

story-board view

.The storyboard view is where the actual content is created. A tutorial is acollection of 

Slides

, and each Slide contains an image, and a block of text. While1

 

2this is the internal representation of the data, the author sees the set of Slides inthe tutorial similar to a photo-reel.Slides can be rearranged, added, deleted, and otherwise modified in a non-linearfashion. The storyboard view also contains a large, functional text entry area wherethe author can write what exactly is supposed to be happening in the screenshot.The text entry system supports a superset of Markdown, with notation to specifyconsole commands, warnings, apt packages, etc.The screenshot can be edited from inside the storyboard view itself. Varioustools for the purpose of cropping, blurring, annotating, and highlighting the imageare provided.The author can save the project and recover from any point to resume editing.Since most of the non-image data is text, it can work well with version controlsystems for collaborative development.

Output

Of course, the most important part of Tuxtorial is to take this data and convertit into something useful. The author can choose one of several output plugins tooutput to various formats. This includes plugins to output to html, pdf, open office,Wordpress XMLRPC, etc.However, the highlight output format is to upload it directly to tuxtorial.comwhere everyone can view it.

0.3 Web Interface

There is a lot of documentation on Linux, but unfortunately all of it is scatteredaround on various forums, blog posts, wikis, etc.A documentation author will be able to upload tutorials directly to tuxto-rial.com from the application. This saves the hassle of finding hosting for images,uploading individually and writing the markup by hand.Each tutorial will get it’s own unique URL, and can be linked to by otherwebsites or found by search engines, where users are provided with a clean, clutterfree interface where they can read the tutorials step by step.In accordance with the spirit of open source, each user will be able to “branch”a tutorial that he/she wasn’t the author of and contribute the changes back. Whilethis functionality is set to be implemented in a later release, the backend is beingplanned with this functionality in mind.Users will also be able to comment on individual tutorials and slides, and alsoconfirm that the instructions worked as planned, to increase the overall trust afuture user will place in said documentation.

 

0.4. RATIONALE 

3

0.4 Rationale

Rationale for writing a separate tool

Why a separate tool only for creating tutorials? Let’s examine the current workflowif you wish to create a screenshot-supplemented tutorial with the tools available bydefault.

•

Take screenshots

•

Save to hard drive

•

Open individual screenshots with editor and edit

•

upload images to FTP/image hosting sites

•

retrieve URLs of each image

•

Write tutorial in HTML, insert ¡img¿ tags for each image

•

Upload HTMLClearly, the workflow features a lot of steps which can be easily automated andoptimized, but nobody’s done it so far.

Rationale for screenshot-based tutorials

Learning material is traditionally text-only or is accompanied by Images or Video.Many points make it clear that the ideal learning material for desktop applicationshave to be images supplemented with text. Some reasons for that are as follows:

Visual feedback

With text-only documentation, there is a significant need to explain oneself andespecially the terminology or “jargon” used. An additional benefit of using visualmedia is that the user can understand whether what he/see is seeing on the screenis expected to be seen.

Size

While pure-text is undoubtedly the most compact, image-supplemented documen-tation are suitably sized for the advantages they offer. Videos are fine but are verylarge and expensive to host and scale for demand.