Thoughts on Documenting a Software Product

Oh man! Ad-blocking software has been detected! :'(

This website is run by the community, for the community... and it needs advertisements in order to keep running. Blocking our ads means your killing our stats!
Please disable your ad-block, or become a premium member to hide all advertisements and this notice.

I am putting this in the "Off Topic" forum since it doesn't quite fit anywhere else and is likely to reach the widest CF audience.

I've been tasked with proposing a major overhaul of our documentation process. Currently, just about everything including the kitchen sink is documented in help files accessed through the product (sorry to be vague, but I can't mention product or business names). In general, the manager for my group describes the documentation as "bloated, often convoluted, often confusing, difficult to find specifics and not as helpful as it could be". He also says he would like me to "own" the documents and documentation process and dictate their direction.

My general philosophy when starting a new job is to keep a low profile, observe, and try to pick up the flow, and then join the flow. I think I've been in that mode too long (almost 3 months) and it's time for me to become aggressive in terms of my management of documentation.

With that in mind, I'm trying to develop a new approach to our documentation process based on diverse audiences and identifying what information should be targeted at which audience and through what means. Help files are only one narrow venue with which to present information to audiences. So far they are almost the only venue used by the documentation person in my group. I need to retool my thinking when I look at our current docs and determine how to "reinvent" the information.

The goal isn't to throw the baby out with the bath water and trash everything, then start from scratch. The goal is to leverage the information that exists and to retool it so that the information is broken down by audience and location so that each audience has access to only the information that is relevant to them. That means not only regrouping data but moving those groups to different venues, depending on where each audience will most likely go for information.

In general, technical documents can take the following forms:

• Online Help
• User manuals
• Technical manuals
• Technical specifications
• Process and procedure manuals
• Business Papers
• White Papers
• Reports
• Marketing Documents

The list isn't exhaustive, but it is generally representative.

Since this is a software project, software documentation can further be categorized as follows:

• Architecture/Design - Overview of software. Includes relations to an environment and construction principles to be used in design of software components.
• Technical - Documentation of code, algorithms, interfaces, and APIs.
• End User - Manuals for the end-user, system administrators and support staff.
  • Tutorial
  • Thematic
  • List or Reference
• Marketing - Product briefs and promotional collateral.

One of the things my manager has suggested is to see what the competition is doing with documentation and to get ideas there. Also, I'm looking at how the overall organization manages documentation and using that information to expand my thinking.

Rather than reinvent the wheel, there is probably more than enough experience on this board to be able to offer suggestions as to how to manage this task. I'd like to put together at least a preliminary draft of a proposal by next week and see how it flies and am asking your help.

While I call myself a "technical writer", the scope of my current position is wider and deeper than my prior experience. That's good in that it forces me to stretch and grow, but I need to be productive at the same time. I'm not asking that you do my job for me, but instead, to provide insights based on your experience in the industry, giving me perspectives that I may lack. The idea is to take what you come up with and integrate it into my situation, allowing me to develop a new construct on which to base my documentation philosophy for my group.

Thanks in advance for your input.

-Trip

 

Oh man! Ad-blocking software has been detected! :'(

This website is run by the community, for the community... and it needs advertisements in order to keep running. Blocking our ads means your killing our stats!
Please disable your ad-block, or become a premium member to hide all advertisements and this notice.

I would be look at different methologies and stealing bits you like. I can't stand doing lengthly documents, I prefer to go for the Agile approach and use DSDM combined with XP, saves time on writing all the crap. The actual manual though is one of those ones which sort of needs to be written at length i would say

 

*bump*

No takers? I figured there were some software gurus out there with a take on how this should be done.

 

Well - software *writers* are famously bad at documentation......

Harry.

 

Interesting question, alhough difficult to give staright forward answer. Because everyone is different in how they learn something. How can you write a manual that everyone understands?

Also I'm a little perplexed that you would want to change your style because I have your book PC Technician Street Smarts and thought it was clear, concise and easy to read. Which to be honest is what a books/manuals should be!

:hhhmmm

 

Trip, I think you might be better off pinging for a database person. From the sounds of it that is what you would need. Then when people ran querys they would have to be in a certain group to acess that information. Sounds like you need something like MS Kb but more user friendly.

 

When did I say I wanted to change the title of my book? This thread has nothing to do with it?

 

If I didn't miss the point, it seems the question is how to make the existing data more useful.
If that’s the case I would tend to agree with Mitzs to speak with a DB developer. An option might include making the information available via a Wiki. This probably wouldn’t be the answer for every type of document or all users, but I've applied seen it work in a call center.

 

I don't think I'm communicating my intent clearly (which in my line of work, isn't a good thing). Let me ask a different question. First off, let's make an assumption about the software we're talking about...it has a client side and a server side. Also, the creator of this product makes the SDK (software developer kit) available to customers so that customer/developers are able to make their own customized applications for the product. I need a list of all potential consumers of all possible types of software documentation. A simple and partial list would be:

End Users
Administrators
Developers

End users of course, would need types of documentation such as quick start guides, HOW TOs, user manuals, and the like.

Administrators would be those folks who administrate the server-side of the product.

Developers, as mentioned above, would make use of the SDK in order to develop custom-made applications for the software product.

Can anyone add to this list?

 

Helpdesk - Support end users questions, issues and complaints
Support / NOC - Those that monitor and support the server side (depending on company makeup, this might fall under Administrator)
Stakeholders / Management - Looking for stats or high-level info on the software

I don't know if this helps, or if these were covered in your original list.

 

What about the client side support people... the help desk types... or is it assumed that the How To stuff would be good enough for them?

 

Good suggestions. Keep 'em coming.

 

Umm... what about the people selling it? Does there need to be anything light and fluffy with a 'sales-type' pitch to it, as in not too technical for the buyers from customer companies or the salespeople from yours? Or are we talking here where the 'market' is set, and the expectation is that those who want it won't need to be persuaded with some sort of sales pitch, rather they just want the hard technical info?

 

One of my projects is to put together a series of training sessions for different audiences including technical sales. Most likely, their current documentation comes from marketing. There is a suggestion that at least some of the documents that currently fall under Marketing's purview should come under mine (in Development). Of course, it's just a suggestion at this point.

 

My only comment in this area is: make sure everything is absolutely accurate. Do not just take a developer's word that something will work. Test it yourself.

I've just spent almost an entire day figuring out what mistakes an author made in documenting the process he was explaining that he himself had created. Even the self-generated documentation from the software itself, i.e. README.txt and INSTALL.txt files were incorrect as to what all steps needed to be taken to get this software creation/install process to work.

I learned a whole bunch about how things work that I probably would have missed otherwise, but I found it very frustrating that the documentation was incorrect and the mistakes had made it all the way through the publishing process because nobody had actually tried to follow the instructions that had been given.

 

I was referring to your style of how you write - nothing to do with the title of your book trip -

 

Sorry. My mistake (I've been making a few, lately).

 

Ok, I've got some "bare bones" in terms of audiences and what document types each one should consume:

End Users (Internal and external):
Quick Start Guides
HOW TOs
User Manuals

Administrators: Corporate admins who are responsible for the server and admin console for the product:
Online Help Files
White Papers
Knowledge Base

Developers: Corporate developers who need to create custom-made applications for the product:
SDKs
Tutorials

Help Desk (external customers)
Online Help
Troubleshooting Guides

Help Desk (internal customers)
Online Help
Troubleshooting Guides

Internal Developers: Those who develop the product for the company:
Wiki
Data Sheets
Code Repositories

This is still pretty rough, but it's getting there.