A methodology is a set of methods, rules or ideas that are important in a science or art. The scientific methodology for troubleshooting SharePoint is a set of ideas important for troubleshooting SharePoint issues based on the traditional scientific method for problem solving. This methodology comprises 7 steps, each step containing several ideas.
1. Define the problem
- Talk to the person that found out about the issue.
- If possible, talk to other people experiencing the same problem. They may approach the problem at different angles getting you different insights, or they may be able to provide more accurate details (such as: how long does the issue exist? When did it start?)
- How long does the problem exist?
- How bad is it (what’s the priority)?
- Identify possible parties (and contact persons) that possibly suffer from either the problem or potentially the troubleshooting of the problem (business people, companies, departments). Also identify parties that may play a role in fixing the issue (dba, network admin, 3rd party vendor, etc).
- Forget what you think you know, don’t assume much and doubt everything.
- Most important of all: forget pressure, try to free yourself from emotions. This will improve your chances to solve the problem a lot.
- Determine what the expected behavior is.
- Determine what is really happening.
- Take the trouble to describe what the difference between both scenarios is?
2. Do research
- Know your environment, know relevant code.
- Read literature.
- Post a forum question.
- Discuss the problem with others.
- Tell it to a rubber duck (which forces you to explain the problem thereby helping you to gain insights).
- If you don’t make any progress within the hour, talk to others.
- Contact other parties that can help you to get more insight into the problem.
- Read the error message with attention, preferably aloud.
- Collect data:
- ULS logs
- Event viewer general info
- Event viewer SharePoint application logs
- Health log database
- Temporarily set monitoring logging to verbose
- Turn on ASP.NET debugging settings
- Decode add-in access token
- Turn on developer dashboard
- Fiddler trace logs
- IIS logs (inc. request tracing)
- Reproduce the problem. Preferably in an environment where you can experiment safely.
- If there is a working environment and an environment with a problem: keep calm, methodically check what is different and the solution will come!
Establish a hypothesis about the problem.
- Ensure the hypothesis is testable.
Design the experiment
- Contact all parties that are impacted by the experiment (typically business).
- Test hypothesis.
- Run automated tests.
- Comment code that is not needed to test the hypothesis.
- Add break points.
- Limit the number of variables you’re testing in a single experiment.
- Try something funny (this probably won’t solve the issue, but let’s try it anyway).
- Eliminate most likely causes, such as:
- Recent code.
- Custom code instead of MS code.
- Do “half-splitting”: eliminate the problem by splitting it in half (comment code, determine if the problem is client-side or server-side, determine if the problem is environment specific and so on).
- Don’t rush. Now is an easy time to break more. Take your time because often you need to temporarily break something to fix it.
- Execute the experiment.
- Take rudimentary notes.
- Try variations.
- Establish the result of the experiment.
- Take some distance and disconnect from emotions while you’re observing what is happening.
- Gather log files.
- Read error messages carefully. We repeat: Read error messages carefully.
- Is the problem solved?
- Did you learn anything? If you didn’t, the whole troubleshooting experience was pretty useless. Remember, even in the unfortunate event where you didn’t solve the problem, there is still value in having learned from the experience.
- Do you understand why the problem was solved?
- Keep notes.
- Add automated test that check for the issue.
- Document failed experiments.
- Enjoy successfully solving a problem.
- Harder to do: enjoy progress.
- Write about it (blog?).
- Update documentation.
- Determine the next step:
- The problem is fixed.
- You need to revisit one of the previous steps.
- You need to get help from others (MS support, external help, another department, colleagues).
Over the course of time we’ve used lots of sources to improve our bag of tricks. Unfortunately, we didn’t keep track of those sources. So, if you feel you need to be credited but didn’t, we’re awfully sorry. Contact us and we’ll add you to the references section.
We recommend you to check out: