1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

Thoughts on Documenting a Software Product

Discussion in 'The Lounge - Off Topic' started by tripwire45, Jan 25, 2008.

  1. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    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
     
    Certifications: A+ and Network+
  2. Toadeh

    Toadeh Nibble Poster

    91
    0
    11
    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
     
    Certifications: BSc(Hons), MCTS Web Development
  3. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    *bump*

    No takers? I figured there were some software gurus out there with a take on how this should be done. :oops:
     
    Certifications: A+ and Network+
  4. hbroomhall

    hbroomhall Petabyte Poster Gold Member

    6,623
    115
    224
    Well - software *writers* are famously bad at documentation...... :p

    Harry.
     
    Certifications: ECDL A+ Network+ i-Net+
    WIP: Server+
  5. UCHEEKYMONKEY
    Honorary Member

    UCHEEKYMONKEY R.I.P - gone but never forgotten. Gold Member

    4,140
    58
    214
    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
     
    Certifications: Comptia A+
    WIP: Comptia N+
  6. Mitzs
    Honorary Member

    Mitzs Ducktape Goddess

    3,282
    73
    152
    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.
     
    Certifications: Microcomputers and network specialist.
    WIP: Adobe DW, PS
  7. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    When did I say I wanted to change the title of my book? This thread has nothing to do with it? :blink
     
    Certifications: A+ and Network+
  8. sunn

    sunn Gigabyte Poster

    1,562
    24
    79
    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.
     
  9. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    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?
     
    Certifications: A+ and Network+
  10. sunn

    sunn Gigabyte Poster

    1,562
    24
    79
    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.
     
  11. GiddyG

    GiddyG Terabyte Poster Gold Member

    2,471
    42
    140
    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?
     
  12. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    Good suggestions. Keep 'em coming. :D
     
    Certifications: A+ and Network+
  13. GiddyG

    GiddyG Terabyte Poster Gold Member

    2,471
    42
    140
    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?
     
  14. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    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.
     
    Certifications: A+ and Network+
  15. ffreeloader

    ffreeloader Terabyte Poster

    3,661
    106
    167
    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.
     
    Certifications: MCSE, MCDBA, CCNA, A+
    WIP: LPIC 1
  16. UCHEEKYMONKEY
    Honorary Member

    UCHEEKYMONKEY R.I.P - gone but never forgotten. Gold Member

    4,140
    58
    214
    I was referring to your style of how you write - nothing to do with the title of your book trip - :dry
     
    Certifications: Comptia A+
    WIP: Comptia N+
  17. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    Sorry. My mistake (I've been making a few, lately). :oops:
     
    Certifications: A+ and Network+
  18. tripwire45
    Honorary Member

    tripwire45 Zettabyte Poster

    13,493
    179
    287
    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.
     
    Certifications: A+ and Network+

Share This Page

Loading...