Authoring Delight

The documentation system tenet of authoring delight states that the documentation system should empower authors with modern and intelligent document editing and processing capabilities. This tenet supports the principles of shared responsibility and low cognitive load by reducing—or preferably, eliminating—any friction which may hinder collaboration.

This tenet sets apart DocOps from all of the other ‘XOps’ practices which are primarily centered on headless automation. In DocOps, user experience is paramount. To encourage users to become active co-creators, “it should be made easy for them to comment on, evaluate, and redirect the information they have received.” (Choo, 2002).

While most other tenets in this text focus on the general user experience, this tenet pays particular attention to the user experience in the context of authoring content.

No amount of automation, search capabilities nor advanced language models can do anything about the lack of primeval source content. The principles of generative content and truth proximity are vacuous if there are no ultimate properties nor truth upon which we can construct our edifice of documentation. 

Even minimal friction points in the workflow of authoring content may result in negative cumulative, exponentially detrimental effects. Reducing the gap between “oh, this is a quick simple edit” and “this appears to be a bit of a hassle”, even if measured in half clicks or milliseconds, is of the essence. An enterprise in which its workforce fails to maintain documentation because of self-inflicted technology or process barriers is lamentable.

Given that content is created in a wide variety of applications, we cannot be particularly specific about the features or gaps applicable to the enterprise’s main documentation platform. The tenet of authoring delight applies all applications, media types, and file formats relevant in a documentation system.

The following is a non-exhaustive list of the most basic ‘features’ that characterize a productive—and thus, hopefully delightful—authoring experience.

• In-place editing: whenever in a document view, editing the underlying content for such a view should require the least number of steps and less amount of visual shift.
  
• Real-time preview: whenever in edit mode, the content should be optionally displayed in one or more of its intended final render target formats, in real-time.
• Typing and grammar assistance: in the context of authoring text, modern tools should help the user in writing text that is grammatically correct and free of typographical errors. 
• In-place content look-up and search: in any type of content and content subset that is within the scope of the documentation system should be referenceable within the relevant authoring workflow without forcing the user to run a separate search.
• Concurrent editing: Two or more users can work concurrently on the same content, seeing the actions of one another in real-time.
• Notes and comments: Users can produce both public and editorial ad-hoc content in the form of comments and notes.

Let’s now look at each feature in detail.

In-Place Editing

In-place editing refers to the capability of editing the content in the same visual context in which it is displayed. If this is not possible, then we should aim to reduce the number of steps and visual shifts involved in the transition from ‘viewing mode’ into ‘editing mode’ as much as possible.

You may see in-place editing with suspicion, but Berners-Lee (1999) actually conceived web browsers as a collaboration tool, and lamented the fact that third party web browser developers were rushing to public their products without such editing support in the nineties:

“Although browsers were starting to spread, no one working on them tried to include writing and editing functions. There seemed to be a perception that creating a browser had a strong potential for payback … As soon as developers got their client working as a browser and released it to the world, very few bothered to continue to develop it as an editor. Without a hypertext editor, people would not have the tools to really use the Web as an intimate collaborative medium.” 

Our goals are to promote collaboration by closing the gap between viewing content and editing and increasing truth proximity by bringing the content’s authoring workflow as close as possible to the context in which it appears.

In-place editing is the ‘idealized experience’ whose viability depends on how close the content is to the default documentation authoring context and how easy it is to integrate and automate the launching of relevant applications. As such, we could judge this feature through the lens of truth proximity, whereby the truth is the content being displayed.

The below table treats in-place editing seen through the lens of truth proximity, together with other proximate approaches.

Proximity	Description
0	Seamless in-place editing: The reading and editing views are one and the same
3	Toggle-based reading/view modes: The reading view can be made editable by clicking on an icon or by the press of a key.
5	Integrated editor: The editor is launched directly from the reading view but it is separate from the reading view. The editor lives in a separate tab, floating window, adjacent pane, etc.
7	Authoring-tool launching: The editor is a different web or desktop application but it can be launched directly from the context in which the relevant content instance appears
19	Source URI and Clipboard: the view provides the underlying source content’s URI and an icon to copy it to the clipboard so that it can be opened from the relevant editor.

Is it key to note that a dogmatic pursuit for in-place editing can actually reduce truth proximity. On one hand, we want to bring the edit capability as close as possible to the content, but on the other hand, we want the content to be sourced from its ‘natural habitat’. For example, for a README.md file whose natural habitat is a GitHub repository, retyping it or copy and pasting it into a wiki page so that it can be edited in place using the main documentation platform’s built-in editor would result in decreasing truth proximity.

Overall content proximity takes precedence over editing proximity; content must never be copied, retyped, or reproduced so that it is closer to available editing interfaces. The objective is the converse; it is to bring and integrate new editing capabilities where they are absent.

Last one note; the term ‘editor’ should not be assumed to refer to only a ‘text editor’. The content may be images, video, etc.

Real-Time Preview

In the late eighties, the emergence of the first what you see is what you get (WYSIWYG) word processors, such as MacWrite on the Apple Macintosh, was all the rage. Before the advent of WYSIWYG technology, users had to exit the editing mode and enter a discrete preview screen. This was the way in which WordPerfect on MS-DOS—provided that users had a capable graphics card—worked. This is the antithesis of a real-time preview.

Similarly to in-place editing, this feature can be seen through the lens of truth proximity, as illustrated in the below table.

Proximity	Description
0	Seamless in-place editing: The reading and editing views are one and the same. The concept of a ‘preview’ is immaterial; what you see is what you get (WYSIWYG).
3	The preview pane is adjacent to the editor pane and it is updated as soon as a change is produced on the editor. The preview pane follows any scrolling, page turning, or zoom actions performed on the editor.
5	The editor is launched in a new window or tab so the user has to reposition the editor and preview windows manually. Other than this, it also follows any scrolling, page turning, or zoom actions performed on the editor.
7	The preview pane is visible at all times but it must be updated on-demand by clicking on an icon or pressing a key. It does not follow the motion actions performed on the editor pane.
19	Generating a preview requires more than a single action; for example, accessing a menu item under ‘File’.

Real-time preview with zero truth proximity—in other words, WYSIWYG—is not always possible nor preferable, depending on the type of content and its semantics. There are many content types—such as mathematical equations—that are more convenient to manipulate in a symboling fashion, rather than in a final output one. It is also key to note that WYSIWYG shouldn’t be used to treat computer screens as virtual paper, which is what ordinary word processors still do today. As pointed by Nelson:

“I think this pandering to the familiar, this emphasis on paper output, may have set progress back considerably. It represented a turning away from the real screen future to placate the lowest conceptual denominator of those who would see the system. This tendency persists today. There is an inane preoccupation with paper: the current stampede for ‘desktop publishing’, and the paper orientation of the Macintosh computer, where everything has a ‘normal size’—the size of printout. The great masses of computer users are still wedded to the Virtual Piece of Paper—the VPOP Paperdigm—because they have seen nothing better. I think we could have set a better precedent in 1969.”

Typing and Grammar Assistance

This feature is the staple of mainstream paper-oriented word processors such as Microsoft Word and Google Docs. Users expect that their text editor will autocomplete phrases, catch spelling mistakes and alert them of invalid grammatical structures. Now that such large vendors are integrating LLMs in the backends, such capabilities will only improve even further, making users even more reliant on them.

Whether typing and grammar assistance is making users ‘dumb’ is a philosophical debate. The reality is that the average user is more productive, and produces better quality content when empowered with such capabilities. Whenever users switch to a more ‘primitive’ text editing environment, such as a Markdown editor, or even a simple text entry field to enter the description of a user story, and such capabilities are absent, they become handicapped.

Many users would rather author their content in a legacy word processor and copy and paste it onto the main online documentation system than risk making spelling mistakes and using questionable grammar. Worse, users may opt to author their content on a legacy word processor and call it a day. In either case, shared responsibility and truth proximity violations are clear.

In-Place Content Lookup and Search

In a mature enterprise documentation system, most documents are composite documents; they are made of content originating from other documents and sources. As such, a common and repeated task is looking up for various content types, and content subsets for inclusion. Such a process should take place within the relevant authoring workflow, without forcing the user to run a separate search.

This is a feature that is actually quite common in several commercial documentation platforms, at least when it comes to documents created within the same platform. The friction arises when referencing external content which forces the user to perform external searches and then paste a URL or content identifier. For example, if a document refers to code or code snippets from GitHub, then the process of searching and selecting such snippets should be part of the same embedding and blending process itself.

Concurrent Editing

Concurrent editing is the ability for two more users to work on the same content unit in real-time, in such a way that all participants can see everyone’s actions in real time.

The most advanced implementation of concurrent editing offer the following features:

1. Notification of what users have joined or left, and who is currently working or viewing the selected content.
2. Real-time display of updated content: modified spreadsheet cells, added text, resized image, etc.
   
3. Real-time display of each user’s cursor or mouse pointer 
4. Implicit versioning linked to each user’s actions.

By definition, nearly all content editors that support concurrent editing are Software as a Service (SaaS) solutions—given that a central server is required to keep track of user’s actions—and are therefore not compatible with the so-called Git workflow given that there’s no file representation of the content under change.

Notes and Comments

When two or more users collaborate on the authoring of a document, it is useful to exchange information to aid the management of writing said document, which may not be necessarily reflected directly in the final document view. Such information typically manifests in the form of notes and comments connected to specific sections of the document.

Some documentation platforms support ‘public’ notes and comments whereby they are attached to published documents for everyone to see. Public notes and comments also align with the principle of shared responsibility. In the words of Bush (1945), “He can leave one item in position while he calls up another. He can add marginal notes and comments.”

Public comments and notes require more thought given that they may go out of sync as the document view evolves. For example, a comment may say ‘This specification is incomplete; there are no performance requirements’. If performance requirements are added later on, the comment must be ‘closed’, at least by having one of the document maintainers reply with ‘Done’. Another possibility is that comments maintain a relationship to the version so that it is clear whether the comment is against the current version, or an old one. 

Reflection

This tenet may come across as too obvious, too general, or somewhat unspecific. You may ask, for example, why isn’t in-place editing a first level tenet rather than merely a feature within a ‘catch-all’ tenet named authoring delight?

The reasons are twofold. First, the themes within authoring delight hinge significantly on out-of-the-box documentation features of an enterprise’s main documentation platform which means that mitigating a poor authoring experience might not be entirely under the DocOps engineer’s control. The second is that tilting the scale thoughtlessly toward authoring delight may conflict with other values and principles; for example, copy and pasting content onto the main documentation’s platform so that it can be edited in place, would go counter to the principle of content-wise truth proximity.