13

Reaching out to ask how others who have adopted teams have approached bringing in existing documentation, especially existing documentation relevant to the entire team that is buried inside some unmaintained github wiki or google doc.

Our goal is broadly to have SO for Teams as the first place to look when trying to work something out, and then SO for Teams will either (a) hold the answer or (b) have a link to where the answer can be found. We don't intend to migrate everything to SO for teams: eg, it can't replace Google Docs/Sheets, and things that are specific to a particular codebase (eg, "what version of Ruby does this need?") should stay in that codebase.

I'm directly copy/pasting things that are both self-contained and relevant to the entire team (eg "Obtaining access to AWS instances via a Bastion host" or "Training expense approval process").

What strategies have worked for onboarding this content in a way that makes it both searchable and well-presented? Specifically, do people "fake" a question and put the existing content in the first accepted answer, or do you just put the content in the question with the original document title as the question's title?

1
  • 2
    I would stick to the Q/A format as long as possible but that is what my gut tells me, not based on real-life evidence.
    – rene
    Commented Oct 20, 2018 at 7:39

1 Answer 1

4

I will tell you what I do and please note there is not a single right answer for this. I can imagine some people / companies putting the answer within the question, linking to external content, not linking to external content, etc.

What I can say is:

Do what you feel is right and get acceptance from your team(s).

What works for you and your team may be different from me or other teams out there. This is why there isn't one single way to do this. I can only tell you what I do...

I usually put up a question but I do not answer it directly inside the question, otherwise the question remains unanswered. So I ask the question, and in most cases I provide a self answer. If the answer to the question can be easily solved with code or simple content I'll answer it right there.

Otherwise if the answer is complex (in addition, long and requires a lot of content, images, sources, attachments, etc.) I will usually do a short tl;dr; of the answer if I can, but then I link to the rest of the answer via a confluence link (use whatever internal / external tool / wiki you may be using, we just happen to be using confluence).

Here's a made up example:

Q: How can I reference our internal employee common data api in a new application  I want to write?

A: To include our common data at acme corporation follow these steps:

   1.  Make a reference to the common data dll found at: <somePath>
   2.  Add a using statement to acmecommondata.emps
   3.  Make a call to GetCommonData()

    You can read more about this entire process here...
(insert link to internal wiki / confluence / any tool you are using that describes the entire solution in great detail)

Just try to make certain you have enough of the answer available in cases where you take down confluence or any wiki type site. These things die over time..so its important to have enough information in the answer to solve the problem.

Not the answer you're looking for? Browse other questions tagged .