Elsa Gonsiorowski

Writing More

gonsie@me.com (Elsa Gonsiorowski) — Tue, 13 Feb 2018 00:00:00 +0000

Meaning
Tip 1: Join a Group
Tip 2: Create Time
Tip 3: Create Space
Tip 4: Writing vs. Editing
Tip 5: Track Progress
Motivation

One of my new year’s resolutions is to write more. As soon as I voiced my goal, it seemed like everyone had, at one point or another, done the same thing. They also shared many pro-tips with me, which I share here.

Meaning

Writing more, for me, is an all encompassing endeavor. It means writing in all forms:

blogging
writing for a monthly newsletter at work
writing release notes for a software project
writing documentation for a software project
writing a daily (personal) journal

For this goal, almost every form of writing counts. The only exception in my mind is email. Emails are for communicating, an instantaneous thing where the words are not typically meant to last.

Tip 1: Join a Group

There are a bunch of writing groups out there and they are particularly active around the start of the new year. Finding a group geared towards your writing style (academic / technical vs. creative writing) is key. If a suitable group can’t be found, at least find a friend. Everything is better with a buddy!

Tip 2: Create Time

Writing takes time and effort. It requires mental focus to organize your thoughts and express them clearly. Creating a schedule with dedicated writing time is essential. A typical suggestion is to write first thing in the morning. Especially if you are (or can make yourself be) an early riser, having a morning quiet time can be powerful.

I find that writing in my personal journal first thing in the morning (acutally second thing, I work out at 5:30 am) is a way to start my day on the right foot. Breaking the habit of checking email and getting sucked in to the internet can be hard at first. But, I quickly found that I would look forward to my writing time and be loath to have it end.

A colleague suggested that I make the same space in my work life. Dedicate some time each morning at work (before checking email) to write. While I think this is a great idea, I’m not sure what exactly I would write about since writing for my blog would not be appropriate.

Tip 3: Create Space

A corollary to creating time to write is creating space. This can be physical or digital. Set yourself up with a nice notebook, a solid desk, and/or an elegant writing app. Find a writing form that is enjoyable and comfortable.

Tip 4: Writing vs. Editing

The same colleague made clear that writing time should be clearly delineated from editing time. Each is an entirely separate process, employing different regions of the brain. Thus, it is important to block out a separate time to edit your words.

I haven’t quite found the way to achieve this yet. Currently, I alternate days in which I write with days in which I edit.

Tip 5: Track Progress

Finally, it is important to track how much you write. This can be used to see your progress over time and as a motivator to keep you on track. I would imagine that many writing groups would use such a writing log as an accountability step.

The exact word-count goal doesn’t matter, as long as you are making progress. I would imagine many writing applications have word counts built in, I am sure there is a way to log this with Emacs and Org mode.

Motivation

Through this effort I hope to achieve a few things:

Fill my blog with content. I genuinely enjoy sharing knowledge with others and teaching people how to do the things I have learned. A blog is a fantastic vehicle to that end.
Fill in gaps at work. I work on software development and, as is typical, documentation is left for later. I do enjoy creating documentation and I would like to make this effort in earnest. Plus, simplifying the documentation process has been on my to-do list for a long time.
Gain more recognition at work. As I tell others, no one knows that you’ve done anything unless you tell them about it (and even then they may not hear you). I would like to practice the art of sharing the accomplishments of myself and my team.
Finally, there is a long list of things I would like to achieve this year. Keeping a daily, personal journal has been something I’ve wanted to do, but I’ve never actually done. I hope that by having a clear focus for each week I can get more done, both in writing and in life.

My Dream Documentation System

gonsie@me.com (Elsa Gonsiorowski) — Mon, 11 Dec 2017 00:00:00 +0000

I have been thinking about writing documentation for a software project, but none of the existing systems that I know handle my use case. At the same time, I've been thinking of reworking my blog and I would like a better Emacs/org-mode workflow. Having a system will allow me to be consistent across all of my projects would mean I could create some Emacs keybindings. This could potentially be fully developed into its own product.

Use Case

For the last year I have been helping to productize a research code. This project should have many kinds of documentation:

Doxygen for browsing the code [audience: developers].
Web-based documentation, with the option to see documentation from the latest features [audience: existing users].
Multiple LaTeX generated PDFs (for user and developer manuals) [audience: newbies].

Requirements

Markup Agnostic: I would like my (unenlightened) colleagues to use this system as well. Meaning, it should support any markup language they choose.
Multiple Output Formats: I would like generate both web-based documents as well as LaTeX generated PDFs.
Simple Organization: The small pieces of documentation should be easy to organize into multiple, larger documents. Not only could users see the documentation in a prescribed hierarchy, but as list of "latest" new features. This would also allow for separate developer and user documentation. One issue here would be ensuring that each headline in the resultant documents is at the right spot in the hierarchy.
Simple to Deploy: The generated documentation should exist both as source code and as deployed content. The deployed content should be updated every time the source is updated.
Simple Software Stack: I want new users to see the power of this system without having to install a huge software stack on their system. Particularly, I teach a ton of undergraduate students who have to use Windows machines (and often don't have root). Thus, each piece in the software stack should be easy to install.

The input/output agnosticism leads me to believe that pandoc is the way forward.

Workflow

Content lives in source code branch under docs/. There are some-sort of specification files which describe the various documents and their contents / hierarchy.
Generation and deployment happens through Travis (or some other CI). The deployed documentation is automatically updated when the source is updated. This deployment could be replicated locally through git work tree.
Deployed documentation lives in a different branch (e.g., gh-pages). The goal is that documentation contributors never have to deal with this branch. In theory, I can assume that there is only 1 website output.

Question: Styling

This raises one question: Where do the styling assets live? Also in the /docs source code? I really like the way the Jekyll handles this.

I think the right answer is that styling information lives in the branch. Designers work on the branch, content development works in source. Plus, there can be as many branches / output documents as you need. But, having to checkout the particular branch to do the styling will probably be confusing.

Setup

docs/
 |-- content/
 |   |-- images/
 |   |   `-- overview.png
 |   |-- group1/
 |   |   |-- feature_a.md
 |   |   `-- feature_b.org
 |   `-- feature_c.rst
 |-- gh-pages/
 |   |-- TOC
 |   `-- CONFIG
 |-- doxygen/
 |   |-- Doxyfile
 |   `-- CONFIG
 `-- user-manual/
     |-- TOC
     `-- CONFIG

Each sub-folder (other than content) is the name of a branch. My system will do something smart with git work tree.

Each output will need know 2 pieces of information:

The order in which the content should exist. Side note: to fully support date-ordering, each piece of content must have a date.
Some (as of yet undefined) configuration settings. Perhaps this includes details on how to deploy?

This information should exist on the source branch. There will have to be some really smart .gitignore files as well.

Needed Functionality

Just looking at the setup, there are number of details that need to be right.

Setup Project
Add New Output
Deploy all

Conclusion

This sounds like a cool new project! I hope I can find some time to work on it.

My Theory of Writing

gonsie@me.com (Elsa Gonsiorowski) — Wed, 17 Feb 2016 00:00:00 +0000

The base of my theory is this: content editing is a completely different process from layout design. Each of these processes is further complicated by real-time collaborations and the necessity for version control.

Git For Everything

As much as possible, both the layout and content editing process should be capture-able by git. Essentially, this means it should be text-based. Keynote presentations (and other complex documents) should not be in a git repository. All generated files, including the document itself, should not be included in the repository.

Content Editing

Text should be edited in plain ascii text files, possibly with markup language (TeX or Markdown).

When using git, each sentence gets its own line. Sentences are the basic unit in writing, using one-line-per-sentence allows for easy parsing of diffs.

Layout Design

Layout design should be a separate process entirely. Layout designs should be codified (such as a LaTeX-style or CSS). The layout design is distinct from the build system which parses the input and uses the layout to generate the end document.

The End Document

The step of building the final document is often overlooked. Many people choose to capture the process of creating a document through makefiles or another build system. Including this is not necessary, since the tool chain is often quite brittle.

Instead, offical or released versions of the document should be included in the repository, with a tag. This helps track submitted versions and can be used to generate track-changes style documents.