Documentation in chat: A case study from the IndieWeb

The IndieWeb has a friendly bot called Loqi that is connected with a community wiki hosted on MediaWiki. The community extensively documents information, ranging from plans for upcoming events to UX patterns for applications relevant to the IndieWeb. The wiki continuously evolves. I regularly find myself saying "Happy newsletter day!" on Friday, celebrating the compliation of all of the information published on the wiki into a single newsletter post.

Loqi has special syntax for creating new entries and adding relevant information to existing entries. For example, I can say:

What is h-entry?

Loqi responds to my question with a definition from the wiki:

h-entry is the microformats2 vocabulary for marking up blog posts on web sites https://indieweb.org/h-entry

This feature comes up in many scenarios. I can ask a question and Loqi might be able to answer it with a relevant resource. If I see a question that I know could be answered by an existing piece of documentation, I can say What is X? and Loqi will respond with a definition and a link to the page. This is particularly useful for documenting technical features. Rather than explaining something that has already been defined by the community, I can ask one question and get a definition and citation in chat.

If a term is not defined, Loqi provides a prompt to define the term:

Me: What is a Mastodon server?

Loqi: It looks like we don't have a page for "Mastodon server" yet. Would you like to create it? https://indieweb.org/s/12Dn (Or just say "Mastodon server is ____", a sentence describing the term)

To define the term, I can use the syntax Loqi provides (Mastodon server is...) and Loqi will create a new stub page on our wiki. This means I can contribute to the wiki without having to leave the chat client. Other community members can see my definition in chat and we can discuss changes if anyone can think of a clearer articulation of a definition. Then, I have a link to a new wiki page I can expand upon. Documenting new terms is quick.

Furthermore, Loqi has syntax to add information to a page:

Me: highlight.js << [https://jamesg.blog/2022/12/30/highlight-js/ James' announcement post for highlight.js]

Loqi: ok, I added "[https://jamesg.blog/2022/12/30/highlight-js/ James' announcement post for highlight.js]" to the "See Also" section of /highlight.js https://indieweb.org/wiki/index.php?diff=85516&oldid=85409

The X << Y syntax tells Loqi to add the contents of Y (in the above example, a link to a blog post I have written) to the X page. This is added to a "See Also" section which contains information related to a topic. This section appears at the bottom of a post. If the "See Also" section doesn't already exist, Loqi will create it automatically.

Here's an example of the See Also section to which I added a link above:

These pieces of syntax are a bit technical and take some getting used to (i.e. if you ask "What is X?" and you mean to ask a person that question rather than Loqi, Loqi will still try to answer). After the initial learning curve, documenting new ideas and adding related resources becomes easier than ever.

One interesting result of combining documentation, chat, and chat logs to which a link can be generated is that we can append links to chat logs in documentation. Thus, if an interesting discussion occurs about a topic, we can document a link to the discussion on the wiki without leaving our chat. This makes it easy to curate relevant discussions that have already happened about a topic. Our community chat logs for all channels aside from #indieweb-chat are public, but this doesn't need to be the case for a system like this to work. As long as you have links to chats, even if they are private, (which platforms like Slack do!), this system could be used.

As a result of the ease with which new content can be added to our wiki and new terms can be defined, I regularly see a lot of activity on the wiki that comes directly from chat. If this feature didn't exist, people would still create pages, but I would expect to a much lesser extent because creating new pages and submitting edits to MediaWiki pages is more difficult than documenting in chat.

How this technology could be applied in a business setting is interesting to me. A "What are the engineer benefits?" prompt could return a company document with all the benefits for engineers. "What is the QA process?" could return a list of steps during a quality assurance stage. This is primarily useful in chat-driven workplaces.

Also posted on IndieNews.

Tagged in indieweb, wiki, documentation.