Effective Documentation for Teams

Introduction

Documentation is hugely important. They say that a company’s most valuable asset is the knowledge inside its employees’ heads, so why not get that info out of their heads and into a place that everyone can access?

I’ve been documenting things for myself and my team for over five years. I document systems, bugs, processes, troubleshooting, outages, and much more. It has saved me many, many, more hours than it has cost me. Just like any other part of your professional life, you want to do it to the best of your ability. It will make your life easier, help your team succeed, and show that you’re a star performer.

This article is written with the software engineering field in mind, but the information is applicable to any industry.

The Problem

Documentation is commonly skipped or half-assed. I often hear the excuse, “I don’t have enough time to write documentation!”. The reality is that over the long term, your documentation will save you time. Overall, your job will be much better if you have documentation.

There are questions that people often have that prevents them from starting their documentation journey, including:
Where will I put the documentation? How can I make time to write documentation? What should I document? Can I put it in too many places? How can I make sure people understand my writing? What does documentation even mean? How do I know anyone will ever see what I write?  What counts as “documentation”? Will I lose job security? How do I organize it? How can I encourage my team to contribute to documentation?

Where do I put my documentation?

Put it somewhere that is easy to access and easy to search. SharePoint is ok. A shared OneNote is better. Confluence is best, in my opinion. My teams use Jira. With Jira you also get Confluence. Most of our engineers are always logged into Jira and thus always logged into Confluence, reducing the hurdle of having to log into yet another system. This increases the amount of documentation your team produces and consumes.

Make a space in Confluence or a shared OneNote and start throwing things in there. Worry about organization later. Do not let perfect be the enemy of done. Keep your documentation limited to one place if you can. Don’t have a Confluence and a Sharepoint and a OneNote and a private Stack Overflow.

I also keep a personal OneNote and document a lot of things for myself. If I feel that those things would be useful to other people, I share them in Confluence.

How can I make time to write documentation?

Documentation is an effort multiplier. You may spend an hour to write documentation, and it will save you many hours over time. I cannot count the number of times that someone has asked me a question about some obscure process, and instead of meeting with them for 30 minutes I can just send them a link to a page on Confluence. This is especially helpful because it’s hard for me to get time to have a spontaneous 30 minute technical conversation without interruption, but if 80% of the knowledge they need is just one click away, I can send that link and carry on to my other tasks. Plus, they can easily share it with others.

You don’t really want to type out the same “gotchas” for connecting to that third-party API over and over, do you? It’s better to just send a link with all that info. There are so many times when it has taken me hours to figure something out that could have been solved in five minutes if there was documentation for it. Those are the things you should write down.

What do I document?

Any time you’ve wondered how a process works, you could document that. If you have had questions about it, there is a very high chance that others have questions about it too. And even if they don’t, you will forget this process eventually and probably have to revisit it and relearn everything.

Or, the first time you encounter an issue you could think to yourself, “This was pretty confusing, but if I knew at the start what I know now, I would have been able to solve this issue quickly.” Then you can write that information down. There are so many times where this happens, and yet people just think “yay I solved the issue :)” and move on to the next issue. If you don’t want to keep solving the same issue over and over, you should document as much as you can.

You can document a specific process with a third party API. You can document columns in the database and what depends on them. You can document your git strategy, your scrum strategy, or your process for pushing code to production. Document all the web pages that new developers should bookmark. Document how to get some code to build after pulling down a repository for the first time. Document your scrum retrospective.

You can, and should, also document events such as outages. Document what broke, when it started breaking, when it was resolved, and what fixed it. You should also document the root cause, and try to get as close to the real root cause as possible.

There is no such thing as over documenting. Documentation will help out your team, and it will help out other teams such as your customer support team and product team, and it will help you out as well. The life you save may be your own.

How can I make sure people understand my writing?

The people who are the best candidates to write documentation are the people who like to write. However, I do not want to discourage anyone from writing documentation. If you have something you think is worth documenting but you aren’t confidence in your writing, just write down what you can. It doesn’t have to be poetry, you can just write bullet points.

Even if you are documenting in a language that is not your first language, people will understand what you mean. They may fix grammar errors themselves, or you can also ask coworkers to review it. Some documentation is better than no documentation! Write away, right away!

What if I write it and no one ever looks for it?
Documentation can be a vicious cycle: People don’t write documentation because no one thinks to look for it, and no one thinks to look for it because no one writes it. You have to break the cycle by writing documentation. I suppose you could break it by looking for it and then complaining loudly to your team when you come up empty, and hope someone else writes it, but I haven’t tried that method yet.

If you write it, they will come. If you think something is worth documenting, there is a very good chance that other people will find it worth reading. That person may very well be the future you. If you got confused about something one time, there is a good chance you’ll have questions about it again.

Even in the worst case scenario, where you document something and no one ever searches for it, it is still worth it to document. Why? Because the process of writing something down will make you remember it. It will also make you realize where you have gaps in your knowledge, and then research to fill those gaps.

What does documentation even mean?

Documentation is anything that you or someone else may need to know. We often forget how much we know. There is a ton of information inside of us that would be lost forever if we left the company or got hit by a bus. These things are documented in our heads, but they could be documented somewhere that is stored in a safe place, accessible by other people.

Documentation can be at the team level or the personal level. I write notes in my OneNote every day. I break it out into notes for each day and also areas where I write notes for various systems, teams, or tasks. Each day if I want to know what I worked on, I just flip to the notes of that day. If I ever leave my job or get let go, I can just share my OneNote with my team and now they have a (slightly chaotic) searchable record of everything I worked on during my employment including the “gotchas” I ran into and how I fixed them.

Will I lose job security?

No, but you will gain the ability to be promoted. No one is a golden cow. No one knows information that is absolutely impossible to be learned by someone else. Companies fire people even when they are afraid to lose them, so don’t think that hoarding information will save your butt. Documenting something is not going to be the thing that tips the scales against you. Be a team player!

Think about it like this: Who is a more valuable person to the company?

• Employee A: Knows a lot and keeps it to themselves. Anytime there’s an issue with something they are an expert on, you have to set up a meeting with them to get the information out of their head. You have to keep going back to them with more questions. It’s a slow process.
• Employee B: Knows a lot and puts it in a place where other employees can access it. When you need to know something about their system, they say: “I’m in a meeting right now but here is a link to how this process works. Let me know what questions you have and we can catch up later!”. Eventually the entire team learns that searching the documentation is easy and likely to solve their issues in a short amount of time.

How do I organize it?

I recommend Confluence for most documentation. It is easy to add pages, easy to edit, easy to search, and easy to share with others. They have useful templates including for how-to articles, sprint retrospectives, and dozens of other things. You can break things into sections however you want; we prefer to do it per team and per product. You should also make use of the labels such as “kb-how-to-article” and “kb-troubleshooting-article” to help you find articles super fast.

The most important thing is to get the information down somewhere. Once that’s done, worry about organizing it. Don’t let organization get in the way of documentation.

How can I encourage my team to contribute to documentation?

Documentation is a vicious cycle. The best way to break the cycle is to just start documenting. Eventually you will be linking people to documentation you wrote, instead of typing out how different processes work over and over and over.

Usually the hardest part is starting a new document. Once the document exists, it’s easy for people to contribute pieces of information to it.

Here are some ideas for encouraging it:

• If you do scrum, bring up in sprint retrospectives that the documentation could be improved.
• Mention it in stand-up meetings and other team meetings. E.g. “yesterday I documented the process for how to make accounts for dogs…”
• Add requirements to tasks that requires the employee to add information about that process to Confluence.
• Create an OKR about creating documentation.
• Give candy and snacks to those who document. Good ol’ classical conditioning!

Conclusion

Creating documentation is rewarding and a great use of time. So many employees complain about a lack of documentation, yet never think to create it. Documentation is a keystone habit that is very powerful once the habit is established. It causes developers and other employees to come to a deep understand of their systems. It decreases the time required to troubleshoot bugs. It makes people think about their processes in-depth and develop process that are clear. It prevents knowledge loss from your subject matter experts. It saves you time.

Start writing documentation today! Even if it’s not perfect, just get your thoughts written down and add to it little by little. Soon, you and your team members will have an impressive garden of knowledge.

Remote Debugging: "The breakpoint will not currently be hit. No symbols have been loaded for this document."

Problem:

When you are remotely debugging your breakpoints show a message that, "The breakpoint will not currently be hit. No symbols have been loaded for this document."

This post is written for a .NET project where you are debugging on one computer (the local machine) and the code is running in IIS on another server (DevServer in this example).

Solution:

Solution 1 - Ensure that PDB files are being generated for your build

On the remote server, navigate in file explorer to the bin folder for your project. This is usually located on the C: drive in inetpub\wwwroot\TheProject\bin. Ensure that there are .PDB files in this folder. If there are not, go back to Visual Studio and change your project's property's so that generated debug symbols are included.

To do this in Visual Studio 2015: Right click on your project and select Properties. Click "Package/Publish Web". Ensure "Exclude Generated debug symbols" is unchecked. You will most likely want to do this for the Debug and Release Configurations.

If you have done Option 1 and are still getting this error, go to Option 2.

Solution 2 - Ensure that you have the same version of code locally and on the remote server.

Before attaching to a process, look at the size of the DLL and PDB files if they are different sizes you may have slightly different versions. This can happen if the code was built using two different methods. For example if the code locally was built using Visual Studio but the code on the remote server was built with release management.

Go to Tools > Options > debugging > Symbols. Add a new Symbol file location for your build server.
Make it point to the bin folder of the project you want to debug. If you have multiple projects you want to debug, add each of their bin folders. It should look something like the screen shot below.

Now attach your debugger to the remote server and confirm that symbols have loaded for your project.

Solution 3 - Ensure you've attached to the right process

Using your browser, navigate to the website hosted on the remote server. This ensures that the process will be running in IIS. In Visual Studio, in the "Attach to Process..." window, find the w3wp.exe process. If there are multiple, try connecting to all of them, but you should be able to tell which one is the website you want. If your symbols are loaded correctly after trying this, you had the correct DLL and PDB files locally and on the remote server, the problem was that Visual Studio was connecting to the wrong process.

It should look similar to the below screen shot.

Solution 4 - Ensure local and Release Management / MSBuilds are generating identical files.

The other solution would be to modify your release management build to make your local build and release management build have the exact same settings so they generate identical DLL and PDB files. This will not be covered in this post because it is outside the scope of this post. However, see the "Other things to try" section below for instructions on manually copying DLL and PDB files from your local machine to the remote server, which would ensure the local and remote versions are the same. However, that is not a proper solution and should only be used for troubleshooting.

Explanation:

The DLLs and PDBs that are generated from a local build need to match the files on the remote server where the code is running. If they do not, or if the symbol files cannot be located by Visual Studio, this error will show up on your breakpoints.

Sometimes you'll build your project in Visual Studio and build that same project with release management or MSBuild, but the DLL and PDB files are different. This can be due to a difference in the build configurations for Visual Studio and release management.

Other things to try:

Manually copy DLL and PDB files from local machine to remote server.

Build the project on your local machine, make sure symbol files (.pdb) are included. To get these symbol files try building in Debug mode. If you still don't have symbol files, right click your project file, and under Package/Publish Web uncheck "Exclude generated debug symbols".
Now find you're project's bin folder in explorer. You should have a fresh set of DLL and PDB files in this folder. The "Date Modified" for any DLL and its matching PDB file should be about the same.

Now find the bin folder for this project on the remote server. It should be the same as what you added to the symbol file locations, so in our example it's \\DevServer\c$\inetpub\wwwroot\TheProject\bin.
Create a backup of this folder just for safe keeping.

Now overwrite the bin folder on the server by copying the bin folder from your local computer to the remote server. The purpose of this is to ensure you have the exact same files locally and on the remote server. This is not a good permanent solution, but if your breakpoints get hit now it proves that your remote debugging is configured mostly correctly and that the problem is a difference with the DLL and PDB files between your local machine and the remote server.

Symbol Status

While debugging, in Visual Studio go to Debug > Windows > Modules. This window can provide you with lots of information for troubleshooting. Look for the DLL of your project (TheProject.dll in our examples). If the Symbol Status shows "Symbols loaded." then things are working correctly.

You can right click on an entry here and click "Load Symbols" to point to a symbol file to use. If Visual Studio likes the symbol files you selected, the symbols will load and the error will go away.

Further Reading

https://blogs.msdn.microsoft.com/visualstudioalm/2015/01/05/understanding-symbol-files-and-visual-studios-symbol-settings/

IIS 7.0 Web Site STIG V-2267 - Request Filtering

Problem

After enabling Request Filtering in IIS for your .NET website, some areas of the application no longer work as expected. This is often done to put your website in compliance with STIG Rule ID SV-32335r3_rule also known as IIS 7.0 Web Site STIG V-2267.

Solution

Add .NET file extensions to the Request Filtering list. These extensions are found here: ASP.NET Web Project File Types.

Begin by adding the extensions under "File Types Managed by ASP.NET", then test the areas of your website that had previously not been functional. If these areas still do not work, try adding the file extensions under "Static File Types" and then "File Types Managed by IIS". Make sure to not add any extensions that are not allowed by the STIG.

It may be regarded as bad practice to add file types to the whitelist that you do not need, so try to only add what you need.

If you have third-party tools that are breaking, those extensions will have to be investigated and added to the whitelist, if appropriate and allowed. Fiddler with help with this, as I explain below in "Other Things to Try."

Explanation

You may think that to find all the file extensions needed for the whitelist, you should explore the files and folders of your website and add all file extensions you find to Request Filtering in IIS. This does not work because there are files that are generated by your app at runtime that have extensions that aren't found in the website's folders. For example, .axd files are a commonly forgotten file extension that will break some areas of your site if they are not included in the request filtering whitelist.

You also need to keep in mind that if you simply allow all file extensions from ASP.NET Web Project File Types, you may be in violation of the STIG. Remember, the point of STIG V-2267 is to limit script execution.

Other Things to Try

Use Fiddler. With Fiddler running, navigate to a page in your application that isn't working and look for 404 errors. These indicate requests for resources that were not found. One reason these files can't be found may be that IIS's request filtering is denying access to them. Look at any 404 errors you are getting and try adding those file types to the whitelist in IIS. For example here is what we would see if .axd files were being denied.

Fiddler results when .axd files are not in the whitelist. Click to Enlarge

Unable to start debugging on the web server. Unable to connect to the web server. Verify that the web server is running and that incoming HTTP requests are not blocked by a firewall.

Problem

When trying to debug  your solution or project, hosted on IIS Express, the following error occurs:

Unable to start debugging on the web server. Unable to connect to the
web server. Verify that the web server is running and that incoming
HTTP requests are not blocked by a firewall.

Solution

Change the project's Web settings to "IIS Express" instead of "External Host". This is under "Web" under the "Servers" section. Visual Studio should automatically fill in the Project Url.

Click the picture to enlarge.

Explanation

When a project's Web settings are set to an external server, Visual Studio will try to connect to that server to debug the project. This would be used if you were running IIS (not IIS Express) on your local machine and wanted Visual Studio to debug the app running on IIS.

Other things to try

• Restart Visual Studio, which also restarts IIS Express
• Run Visual Studio as Administrator.

"Cannot obtain value of the local variable or argument because it is not available at this instruction pointer, possibly because it has been optimized away."

Problem

While debugging in Visual Studio 2015, many variables are not available. When you try to see a variable's value, Visual Studio tells you, "Cannot obtain value of the local variable or argument because it is not available at this instruction pointer, possibly because it has been optimized away."

Solution

Change the "Solution Configurations" drop down to "Debug".

Explanation

According to Microsoft: "In Release, some locals will be optimized away and will not be available during debugging."

This is done for performance reasons. You can read Microsoft's excellent post on the issue here.

Other things to try

• Uncheck Project Properties > Build > Optimize Code. (For Visual Studio versions prior to 2015)
• "In Visual Studio 2015 this option is off by default but if you must debug an application compiled Release, you can turn it back on under Debug -> Options and check “Suppress JIT optimizations on module load (Managed only)”." - MSDN Blog

"Variable is accessed within inner class. Needs to be declared final."

Problem:

"Variable is accessed within inner class. Needs to be declared final." or a similar error occurs.

Solution:

Declare the variable final, or make it an instance variable.

Explanation:

Java doesn't want developers to change local variables from within an inner class or an anonymous inner class.

Inner Classes and Local Variables

Any variable defined in a method and accessed by an anonymous inner class must be final. Or, as Oracle says:

"An anonymous class cannot access local variables in its enclosing scope that are not declared as final or effectively final"

Note: "effectively final" is something new introduced in Java SE 8. It is defined as a variable or parameter that is not declared as final, whose value is never changed after it is initialized.

But why make it so inner classes can't modify variables belonging to their outer scope?

The reason is that the inner class "captures" the variable. To understand why this matters, we need to understand the implications of how captured variables work. If you are familiar with closures, that is exactly what's going on here.

The inner class is a closure. It copies the variable from it's enclosing scope to a new variable, and brings just that copy inside the inner class. Anything it does to that copy is independent from the variable in the enclosing scope. So if the variable changes in the inner class, and then it is used later in the enclosing scope, the changes made in the inner class did not persist in the enclosing scope.

Basically, what happens in the inner class stays in the inner class.
Below is a proper scenario.

 
public class RadiusStuff { //This is the outer class
    public void start(Stage stage) { //This method is the enclosing context
    Button submit = new Button("Submit");
    final string radius = "10";
    submit.setOnAction(new EventHandler<ActionEvent>() {
        //This is the inner class, specifically an anonymous class.
        @Override
        public void handle(ActionEvent e) {
            submit.setText(radius);
        }
    });
  }
}

This functionality is by design.

Java wants the developer to use the final keyword on any variables that are going to be modified in the inner class. This prevents us from thinking the things we change in the inner class will persist in the enclosing scope.
In a way, adding the final keyword does not change the behavior of the code. Think about it. With or without the final keyword, any changes to the variable in the inner class won't persist, so why make any changes at all? Java forces developers to use final in this scenario just to emphasize that we shouldn't be modifying a local variable in an inner class.

But what if, in the closure, we are only reading from the variable and not writing to it? Does it still need to be declared final?
If you are using Java 7 or below, the answer is "yes".
In Java 8, if we are only accessing but not changing the variable, the variable is "effectively final" and does not need to be declared final.

The problem with this is that if we ever want to change the variable we won't be able to. In the below code I show an example of this case by assigning a new value to our "radius" variable, but it will not work.

 
public class RadiusStuff { //This is the outer class
    public void start(Stage stage) { //This method is the enclosing context
    Button submit = new Button("Submit");
    final string radius = "10";
    submit.setOnAction(new EventHandler<ActionEvent>() {
        //This is the inner class, specifically an anonymous class.
        @Override
        public void handle(ActionEvent e) {
            submit.setText(radius);
        }
    });
    radius = "15"; //This will throw compile-time error.
  }
}

Instance Variables

I mentioned under the "Solution" section that we could also just make the variable an instance variable. Does this really work? Why?
Referring back to Oracle's documentation we see that our inner class "cannot access local variables in its enclosing scope that are not declared as final..."
So why would an instance variable be an exception? Note the words "local variable". This only applies to variables declared within the method that the inner class is in, also known as the "enclosing scope".
So does this mean an anonymous inner class can change an instance variable, and have those changes persist outside of the inner class?
Yes.

 
public class RadiusStuff { //This is the outer class
    string radius = "10"; //Instance variable, no need to be final.

    public void start(Stage stage) { //This method is the enclosing context
    Button submit = new Button("Submit");
    
    submit.setOnAction(new EventHandler<ActionEvent>() {
        //This is the inner class, specifically an anonymous class.
        @Override
        public void handle(ActionEvent e) {
            submit.setText(radius);
        }
    });
    string radius = "15"; //This is allowed now.
  }
}

Other notes:

• Variables defined in interfaces are implicitly final, even if they don't have the final keyword.
• For variables that reference objects, the properties of the object can be modified, even if the variable is final. However, you cannot change which object the variable refers to.
• You can find excellent information on closures here: C# in depth
• The behavior mentioned in my post is similar between Java and C#, but there are some differences, so be careful. Perhaps I'll discuss those in a future post.

"System.ComponentModel.Win32Exception: Access is denied"

Problem:

The following error is encountered after publishing a website:

System.ComponentModel.Win32Exception: Access is denied[Win32Exception (0x80004005): Access is denied]
[ExternalException (0x80004005): Cannot execute a program. The command being executed was "E:\someDirectory\myWebsite.com\wwwroot\bin\roslyn\csc.exe"

Solution:

Change the .NET application's framework version to 4.5.

Also erase  the <compiler> section from the web.config if it's throwing an error when you build.

Explanation:

This happened to me when running Visual Studio 2015, and publishing my website with a .NET version of 4.5.2, on my Personal Class ASP server on Arvixe. I noticed the problem did not happen when I was using a different computer with an older version of Visual Studio 2015 CTP. I noticed that the non-working version of VS was setting the target framework to 4.5.2, but the version of VS that was working for me had it set to 4.5.

The version that did not work is:

Microsoft Visual Studio Enterprise 2015
Version 14.0.23107.0 D14REL
Microsoft .NET Framework
Version 4.6.00081

The version that did work is:

Microsoft Visual Studio Ultimate 2015 CTP
Version 14.0.22609.0 D14REL
Microsoft .NET Framework
Version 4.6.00030

To fix this, open up Visual Studio. Open the Solution Explorer.

Right click on "WebApplication1" (or whatever you named your app) and then click on "Properties".
You'll be presented with the following window.
Ensure that "Target Framework" is set to 4.5. Hit Ctrl+S to save.

If you previously built with a target framework of 4.5.2, you may have a <compiler> section in your web.config, and this may throw an error when you build. Just remove this section to fix the issue. Removing it should not cause any problems.

That solved it for me. It may not solve it for you depending on the configuration of IIS on the server you're deploying to. If it didn't work, check below for other things I tried that didn't work for me but may work for you!

Other things I tried that didn't work:

• In IIS, Enabled Basic Authentication, disabled Integrated Windows Authentication.
• In VS when publishing using Web Deploy, I selected to exclude app_data files.
• Tried running VS as admin
• In IIS, checked "Enable write permissions" and "enable directory browsing",
• Deleted everything from wwwroot and published again
• Changed platform target from "any cpu" to x86 in web application build settings.
• Changed platform target from "any cpu" to x64 in web application build settings.