We have a plan, and now we can start.
We decided how we will save the data, and who will write it. So what now?
Documentation documents and manuals
You might be tempted to start with How-To, manuals and guides.
I am suggesting you don’t. The reason we start with form style documentation is that we need a good asset view to know what we will be documenting later.
You can start writing procedures though if you have a team, and have technical writers on it. Technical writers might not be full time, but I have worked with full time technical writers. For example, the Level 1 team is a great technical writer team if they have the time, as they have to repeat procedure multiple time to the users. But not all technicians are good technical writers, and you should already have a better structure before they start writing documents.
Documenting the documentation
Since it is quite likely you will ignore my suggestion and keep moving ahead, then let’s start by documenting the documentation. Basically, you need documentation describing the structure of documents, meaning a link tree, and the hierarchy of documents. You also need to document the style, so the documentation is more consistent, and what are the goals and requirements for documentation.
You have to have in mind the many different types of documentation as well.
For example:
- How big and how often should pictures and screenshot be included in documentation
- How to break documentation
- Hierarchy of headers
- Meta information for the documentation.
- Separate styles for different audiences
- Repository of documents
Folder Structure
This is important, and sometimes it can be a problem. We like to make separation, sometimes we separate too much.
Try to avoid doing too much hierarchy classification, unless you have hundreds of documents all together, and at that point, the separation will come more natural.
For example, I like to have 2 folders, one for Public and the other for Internal. The public is to share with customers and end users, the internal is for technicians.
The public folder rarely has subfolders, this way end users can see all the guides in a sorted view.
For the internal folder, I avoid subfolders, but they are more needed. What I do avoid is creating unnecessary subfolders.
For example, this is a bad hierarchy
knowledgebase (internal)>Documents>Equipment>Cisco>Switches>Catalyst>WS-2960>Recommended setup
Those are too many subfolders. This is better
knowledgebase (internal)>Documents>Equipment>Cisco Catalyst WS-2960 Recommended Setup
We moved a lot of the description to the title of the document. And if we use similar naming, all documentation related to Cisco Catalyst will be together in a view, or a filter.
This is just an example for wording, as we also try to avoid such specific documentation
Naming Structure
As I demonstrated on the example, the document title is important. VERY IMPORTANT!
The title is used in meta search, and regular search. We should not be afraid of a wordy title, but also not add unnecessary wording. The title itself should be a short description sentence. And if you have multiple locations, customers or data sets, it should be on it.
I like to use “space dash space” ( – ) to separate descriptions blocks, for example short company codes to separate documentation from different companies, or networks.
Network configuration and details – VLAN 199 – Main location – Customer
Network configuration and details – VLAN 1 – Satellite – Customer B
Those 2 titles are for the same form, but they are different networks, sites and customers.
The naming standard will depend on the type of documentation you make, but it should be consistent across the company.
For example, always use spaces before and after the dash, customer name always goes at the end, and location goes before the customer when there are multiple locations. Those are just some rule examples.
Lessons learned and pitfalls to avoid
The reason I use dash, is that underscore is difficult to read when there are lines.
The space before and after the dash can increase the character count, but makes search easier in most programs.
Capitalizing the first letter of every word in a title looks cleaner.
Non-essential information should go at the end in case that the text is truncated. For example, since company can be filtered by walking thru hierarchy, it is not needed at the front.
Special characters should be avoided in names.
Avoid making too many changes to style if not using a product. Spending too much style on style is inefficient. This is another reason a wiki is a good tool.
Start with forms first, and start small. You will find lots of errors, improve documentation style, and the form, so you want to avoid having to revise too much the initial work.
Changes to documentation will happen. Just accept them.
Not everyone will like your style or respect it, however be open to make changes to get more people onboard.
The hardest part is to get people onboard with documentation. Even when everyone nods yes, it will take a long time to get it out of the ground. Do not give up.
You can convert current sources to documentation, for example the ticket system.
You will find lots of ways to improve or automate the process as you go thru it.
Did I mention not to give up? The more you document, the more useful it becomes.
DehcTech 