Lets talk documentation and how you do it

We all know the importance of documenting work, it is a mantra that is constantly repeated in all technical industries, but what is rarely mentioned is that most of us suck at it, and some of us find ourselves not doing it at all. So I wanted to start a discussion getting as many suggestions of actually HOW to document, and what tools you use to do it.

There are many forms of documenting, such as:

  • Todo list (simple checklist)
  • Task list (possible due date, comments, notes, attachments)
  • Project list (projects made up of multiple people, posts, comments, attachments, documents and revisions, calendar)
  • General notes (just interesting information, tips, tricks, tools, knowledge for your job)
  • Knowledgebase & Q&A (specific documents detailing specific tasks, duties, procedures, how-tos)
  • Support ticket systems (user-generated questions, problems. Ticket resolution and eventual filing into KB or other)
  • Chat (general work-related chat, group chat, meeting notes, file sharing, note taking, idea sharing. Needs to be indexed, filed, searchable, project centered or group centered, etc)
  • Document store (Documents, spreadsheets, graphics, reports, policies. Shareable, protected, revisioned, audit-trail, linked to projects, tasks, groups, jobs, KBs, emails, support tickets, how-tos)
  • Scratchpad (we all need to keep small temporary notes while working. Do you keep these forever as well? A text document open, sticky notes on your desktop?)

The list goes on.

There is not one single too that does it all. For example, a simple todo list is generally not useful if it is thrown in to a large complicated application with a huge UI and so forth; it must be small, simple, easy, instantly accessible, and useful.
A support ticket system is great, but not if the tickets cannot be easily converted to KB articles and properly tagged, categorized, and accessible through email structures, and searchable in a front-end by end users.
Cloud document sharing services are great, but not if it’s difficult to manage users, revisions, and linking into projects or KBs from some other tool.

So my question is this: given all these different types of documentation needs, what do you use to store, sort, index, archive, search, manage, and otherwise work with documentation and all related files and collaboration?

  • Standalone desktop programs?
  • Corporate/enterprise KB management systems?
  • Self-hosted Intranet website (Wordpress etc)?
  • Ticketing portals such as Freshdesk?
  • Wiki software?
  • Folders and folders of shared Office documents?
  • Cloud drives with folders and folders of Office documents?
  • Collaboration cloud tools?
  • Email only?
  • Homegrown database?

I am curious about this, because everybody says to document, few have any real world advice on actually doing that or what tools to use!

There are many ways to do all this wrong as well. Documentation becomes out of date fast and doesn’t allow comments or revisions. Poor searching. Improper or lack of user management, roles, permissions on the information. Poor structure, or overly complex structure (i.e. makes it difficult for anybody but you to use the system). Perhaps the tools are half baked, too expensive, don’t have necessary features, or are too cumbersome to deal with.

So, we want a clean method of documenting our work, our collaboration, our communication, our jobs, tools, tasks and procedures; documenting our projects, files, calendar/schedule, and our support KB.

How do YOU do it?

Great question. Documentation is very important to me, so this is how we’ve been working in the past:

Todo list / Task list / Project list: we use our own agency management software, Simpfinity (we’re preparing it for public use).

General notes (just interesting information, tips, tricks, tools, knowledge for your job): we post this sort of thing on a private Google+ community. This is a great tool for people to share stuff with the company when they don’t need an immediate reply, or any reply at all, and when they don’t want to interrrupt their colleagues (when the answer can wait).

Knowledgebase & Q&A, Document store: Docs on Google Drive. We have a folder “How we do things in our agency” and we create everything there. All the templates are there, policies.

Support ticket systems: our own app, Simpfinity (it’s connected to a support@ email address and everything clients send to that address ends up in their project in the app as a ticket / work unit; we answer tickets from within the app, so we don’t have to use Gmail).

Chat: we use Google Hangouts. These are searchable from within Gmail (we use Google Apps, so Gmail is our primary email client). If there is anything actionable mentioned in the chat, is is not allowed to stay there, we convert that to tickets immediately and forget about chats. I can’t remember when was the last time I had to look for something important in a chat (and we are a remote agency with people working in three cities). If something needs to be done, it needs to become a ticket.

Scratchpad: good old pen and paper :slight_smile: I throw away those papers every day.


As you can see, we’re Team Google and most of our work was once based on their apps + our own app.

Now, in the future, we will ditch Google Drive as our document store, because we’re upgrading our app Simpfinity to be able to handle files and documentation. This is tricky to organize well because there are three types of documentation: agency-generated, client-generated, and third-party generated. Our goal is to organize all of agency’s work within one app: sales, tasks, projects, client support, documentation. If it’s closely work-related, it needs to be in one place and integrated - that’s how I view an ideal workflow.

For the time being, I’m fine with having chats and non-real time discussions in Hangouts and Google+ communities. If I lose this data tomorrow, my business won’t be affected much.


I hadn’t thought about using a social community like G+ for business.

Do you have employees use their own personal accounts or is this a business thing where user accounts are controlled by the company?
I think it would be difficult to convert a company to this if they aren’t used to it already, or don’t use gmail, etc etc

Can you chat via any desktop tools or do all your users have to log in with the browser and keep a tab open all day?

We’re using Google Apps for Business accounts, which means that the company controls employees’ accounts from one central place. These accounts are good for Google+ and for Google Hangouts (the chat app). We also use Google login for other apps, for example for our project / helpdesk app or CMS installations, which means that as people get hired or leave the company, we’re able to control their access to crucial agency infrastructure with one push of a button. That’s the best feature of Google Apps, one that too few business owners take into consideration. This is so much better than using Skype where people did use their personal accounts in the past, and I can tell you this is not the most fortunate scenario. The company needs to be able to control access and its data at all times, even when people leave the company.

Google Hangouts, unfortunately, is not a standalone app, so we need to have Gmail or Google+ active to be able to chat.

It’s not so hard to convert a company to Google Apps. You get business-grade email with that, office apps, Drive, and many other things. You don’t have to use Gmail if you don’t want to. The main competitor to Google Apps is Microsoft with its Office365 product. We’ve been with Google Apps for a couple of years, we like it.

I do have one followup. A company I work for has 6 to 12 employees so they could probably afford the costs. But they work with 40+ contractors who are like employees but not really. They wouldn’t want to buy accounts for all them, but still need to work with them.
Does the Google apps allow non-company connections to collaborate? They might need access to a special calendar, chat system/group chat, possibly video conference. Access to certain document folders etc etc.
Does Google apps allow certain collaboration with non-company accounts in this way? What can it allow and what is not allowed?


Yes, your company will be able to collaborate with people who log in from non-company domain. It’s not a problem to share documents / folders with outsiders, and the permission system inside Google Apps is solid. You’ll also be able to invite people to hangouts (which is a text + video chat app, and if I may add - the video capabilities are awesome! You can stream hangouts as “Hangouts on air” in real time and instantly record videos on Youtube out of that, works out of the box).

The only thing you must be careful is this: documents / folders created by people who are logging in with non-company domain will forever stay in their ownership. AFAIK it’s not possible to transfer ownership of a document to and from the company domain. For example, if a contractor john.doe@gmail.com creates a document and shares it with your company, this document is his to do with it whatever he wants; he can delete it and deny access to it. The only way the company can retain that document for later use, is for someone logging in with @yourdomain.com to create a copy of the document, and continue using it.

Contractors, of course, don’t have to use @gmail.com accounts to access your company’s Google Apps documents; all they need is a Google account, registered with any email address.

Thanks for asking! Let me know if there’s anything else you’d like to know about collaborating with Google Apps!

Sorry, this conversation is going a little off topic but I’m curious about Google Apps.
I guess I’m just stuck like, you can pretty much do everything with free Google accounts that you can with Apps. The only real advantage seems to be maybe some extra storage, and some control over add/removing users with domain email accounts.
I read in their FAQ that even for paid domain members, if you later delete them, it also deletes all their content like documents, images, posts, etc. This seems wrong to me, like if I have a marketing guy and I later delete him, I don’t want all that work he did for my company to just disappear, it could contain important stuff for the next marketing guy!

I’m just trying to find out what the real advantages are to doing things with Apps that you can’t already do with regular accounts. You still have Hangouts, chat, email, cloud drive, collaboration, circles, posts, cloud docs, etc etc So why buy accounts? Just to use our own domain for email? We already use our own domain for email on our own server.

The whole Google universe is already confusing but most of the “features” of apps you already get with regular accounts. Let’s say all our employees create personal accounts, we set up connections between each other and circles for certain communications, etc. Nothing really changes.

The only thing would be, there is no “shared” document store I guess. But all our users share docs over a Box account. I don’t know, have to keep researching.

No problem, happy to answer.

“The only real advantage seems to be maybe some extra storage, and some control over add/removing users with domain email accounts.”

That, and support from Google (or from their partners who resell Google Apps) if anything ever goes wrong.

Let’s talk about the price of loss of data vs. the price of Google Apps. Apps costs your 12-employee company $600 annually. For that price, you never ever have to think about employees denying you access to crucial information. I am willing to bet that your company has documentation that is worth much more than that. For example, in our agency, we crowdsource creating documentation for everything. We have documents that have been created years ago, that we use every week, and which we improve every time we see a “bug” or an imperfection in them. How much can a document, that employees have spent hours to build, and is used every week, be worth to you? Let’s say that your company spends 50 hours over three years to build a document which you don’t want to lose. To break even with the Apps cost, your hourly fee would only have to be $12 / hour (50 hours x $12 = $600). I am sure you charge more than that. And then, let’s say that this document is accessed once a week by two people for reference purposes: how much is having that knowledge at your fingertips worth?

Let me give you two examples of important documents and how much they could be worth to my company.

Example #1: I’m not a developer, and I don’t use Git source control every day, but I must use it from time to time. For that purpose, my developer has taught me how to commit, push and pull stuff to and from our servers. BUT I regularly forget how this is done, so I wrote the procedure in a document (which is available to everybody). Without that document, I’d have to bug the developer all the time, interrupt him in his work every time I want to commit a line of code. How much do these interruptions cost? Also, how much does a company save when another non-technical employee needs to be taught Git?

Another example: we use a clunky, complex app that handles recurring billing for domains and host packages. Nobody in our company likes it, but there is no better option on the market if you’re selling domains and hosting (that’s a relic from our past we can’t wait to get rid of. But I digress.) Anyway, there’s a written manual for using that app, one of my partners have written it years ago. Failure to use that app properly has already resulted in thousands of dollars of real damages to my company: employees failing to enter recurring services, so we failed to charge for some of them. They haven’t read the manual, or read it badly, and it cost us money. But it cost us only thousands of dollars, luckily we never lost a domain and it never happened that a website went down - but imagine if we did because someone didn’t follow the procedure?

Now imagine having a rogue employee denying access to crucial documents like those - imagine documents just vanishing over night, and you haven’t made the backup, ever. I bet $600 is not that expensive anymore.

Deleting users: you can import their emails to another account (made to be an import-all, for-archive-only, searchable account). In case another employee comes to the company for the same position, he/she can get access to that search-only account, BUT if you’ve organized your company well, nothing important ever will be kept in an email message! I half-jokingly say that email is for spam, jokes, and purchase receipts only (not even for jokes anymore: that moved to social media). We do have such an import-all account and we may have used it a couple of dozens of times, BUT everything actionable is kept in our sales / PM / helpdesk app.

You can transfer the ownership of their documents to someone else within the company (that one is easy, as long as you’re all on the same domain). That way you don’t lose anything.

I see the same mistake being made with companies using Dropbox and not paying for business Dropbox account. The true cost of business-grade infrastructure gets revealed once you lose data. Think of Google Apps as $600 insurance, with which you can sleep peacefully at night.

Sorry for writing so much; I have real, costly, painful experience with the topic, and I’m passionate about talking about the true costs of doing business.


This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.