In general, it's considered good practice to keep documentation close to its context. Use comments within source code, put low-level requirements in ticketing systems, store user information for version control repositories in README files, and so forth. This ensures visibility and lowers the barrier to long-term maintainability.
However, there are instances that call for a communal content repository apart from these mediums. Such repositories provide a means to easily create, collaborate on, organize, and share content within and across groups that are part of a larger organization.
So, how do you solve this problem? Do you already have a solution in place? If so, have you noticed gaps in how its features meet your needs and considered alternatives? If not, what points do you consider when evaluating prospective solutions? Let's talk about this.
The nature of content can be quite diverse: notes and agendas for meetings, project proposals and requirements documents, architecture and design documents, etc. As such, the ability of a solution to format and display multiple types of data for a variety of audiences is an important consideration.
Additionally, the technical savvy of any given user may be equally diverse. A secretary, a manager in human resources or finance, a project manager, a designer, and an engineer may all be using this solution for their own purposes. This requires a low barrier to entry for usability, facilitated by features such as an easy-to-use WYSIWYG editor over a markup format (or, ideally, both), particularly proprietary formats that may impose vendor lock-in.
Host operating systems may also be a limiting factor. Some users may need a solution that works on iOS or Android as well as on the desktop. A few solutions, like Quiver and Notion, only run on OS X, which may not be the preferred choice for professionals in the longer term.
It's been said that the "software is eating the world, and the web is eating software." These days, it's becoming more commonplace to offer progressive web apps over native apps, or to at least offer multiple clients backed by a common web service. As such, solutions tied to a particular platform may lose their efficacy.
In my experience, many solutions fall short in this area. It's great to be able to easily create and maintain content. However, after the amount of content contained within such a solution reaches a certain threshold, the ability to organize and discover content is just as important.
I've often heard phrases like "the wiki is where content goes to die" or "content rot" with respect to these sorts of solutions. If a user can't easily find the content they need, or if that content is difficult to maintain, the solution that hosts it is considerably less useful.
Let's take Atlassian Confluence, a commonly used solution for this problem, as an example.
Content must be searchable. To that end, it must be possible to separate content into high-level groups to limit search context. Confluence does support something akin to this in its Spaces construct. However, that construct is only used to provide context for page browsing; it has no visible bearing on search. The organization of Spaces is limited to a single global namespace with some basic filtering and categorization.
Confluence uses a hierarchy for page organization. I've often found that their implementations of this hinders rather than helps content discovery after reaching a certain point of granularity in the hierarchy. Confluence also supports tagging pages with labels, but the feature doesn't have a very prominent place in its user interface.
Finally, the search implementation itself must allow for granular search based on various aspects of a page. Confluence offers a very basic implementation that searches titles and textual content and offers a list of recently viewed pages. There's significant friction involved in locating pages authored or edited by a particular user or locating pages that haven't been edited or viewed within a certain period of time. Such features are essential in facilitating "wiki gardening," or keeping information contained within a solution current, well-organized, and well-formatted.
Many companies use solutions like Slack for real-time internal communication. Slack in particular is well-known for the out-of-the-box integrations it offers with other software, such as Atlassian's JIRA ticketing system. An ideal solution for managing content would integrate with tools like these and others within a company's workflow, such as developer IDEs.
Such integrations could take several forms. One could enable users to keep abreast of recent content changes. Another could proactively seek out opportunities for users to collaborate and contribute. Yet another could help to facilitate peer review of content changes prior to publishing.
Finally, solutions could integrate with other systems like JIRA to render their data in useful ways, such as Confluence supporting the embedding of a list of JIRA search results on a wiki page, or JIRA listing what Confluence pages reference an individual ticket on the JIRA page for that ticket.
To facilitate this sort of integration, some companies like Microsoft offer suites of tools like OneNote, OneDrive, and SharePoint that integrate reasonably well to share data.
There are numerous possibilities for integrations. Solutions that do not offer them are considerably less useful for it.
Hopefully this post has left you with a broader outlook of what to consider when choosing a solution for internal content management or an alternative to an existing solution. I'd love to hear about your own toolchains and experiences in the comments. Thanks for reading!
