How Does Your Company Organize Its Internal Content?

in #technology5 years ago

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.

Content and Audience Versatility

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.

Organization and Curation

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.

Integrations and Discoverability

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!


This is a good writeup. My company uses Slack for communication, and we love it since it's browser-based and therefore platform-agnostic. We also had a group write a custom integration that assists people in carpooling to lunch.

I do have some conversational criticisms:
Comments in source code doesn't work as well as one might hope; nobody wants to try to keep comments up-to-date after the fact. I believe code should be self-documenting: do a solid job of naming classes, methods, and variables, and you'll be better off.

I also have to disagree with, "put low-level requirements in ticketing systems." In my experience, adding extra unnecessary steps to software development will only bog teams down (and they probably won't follow through with it consistently, anyway). My teams deal with product managers which write the tickets/cards/stories for us (they give us work to do, and we do it) and so it wouldn't make any sense for them to write anything more detailed than the high-level requirements.

Thanks for reading and for leaving a comment!

Comments in source code doesn't work as well as one might hope; nobody wants to try to keep comments up-to-date after the fact. I believe code should be self-documenting: do a solid job of naming classes, methods, and variables, and you'll be better off.

To a degree, I agree with you. However, I still find usefulness in sparse comments that explain why something unintuitive was done the way it was, often linking to external resources like relevant bugs in third-party libraries or services, the language itself, etc.

I also have to disagree with, "put low-level requirements in ticketing systems."

Again, in general, I agree. However, it depends on the nature of the work being done and who's writing the requirements. As an example, my workplace recent began a large-scale effort to cull some of our technical debt. The developers are the better people to write requirements in that instance because they're familiar with the nature of the debt and the best way to go about resolving it. I suspect this also varies on a more general basis from company to company; some may put high-level requirements in requirements documents and lower-level requirements in ticketing systems.

Sometimes progressive web apps are better than native because of device limitations and data. PWA takes less storage and memory and network bandwidth

Congratulations @elazar! You have completed some achievement on Steemit and have been rewarded with new badge(s) :

You got your First payout

Click on any badge to view your own Board of Honor on SteemitBoard.
For more information about SteemitBoard, click here

If you no longer want to receive notifications, reply to this comment with the word STOP

By upvoting this notification, you can help all Steemit users. Learn how here!

Congratulations @elazar! You have received a personal award!

1 Year on Steemit
_Click on the badge to view your Board of Honor.

Do you like SteemitBoard's project? Vote for its witness and get one more award!

Coin Marketplace

STEEM 0.21
TRX 0.06
JST 0.028
BTC 19033.33
ETH 1057.90
USDT 1.00
SBD 2.96