Skip to main content

View Diary: Our networks don't always work so well (84 comments)

Comment Preferences

  •  Testing and manual/help writing (2+ / 0-)
    Recommended by:
    ferg, Notreadytobenice

    These two things always are put off to the last minute and always get slighted, was my experience in a former life in Silicon Valley.

    This is a very complicated system with many calls to outside legacy systems. Unfortunately the beta is happening now. But it almost could hardly have been elsewise, give the necessity of keeping it all away from spying Republican nitpickers during development

    The Washington Post has a really good but kind of sad major article about the development program and the people at the top of the project on the government side.

    It is fixable. The ACA will make a big difference for the better for a lot of people.

    •  manual/help writing? This layman's experience... (0+ / 0-)

      has been all tech manuals are written by those who have taken advanced bad-writing courses.

      •  No, not all of them (5+ / 0-)

        Many manuals, and sometimes also the user help systems, are written by software engineers themselves, who are given this task because it is assumed they are the ones with the technical knowledge, so who else could do it? And many companies don't see a value in hiring professional tech writers who can translate into non-technical terms for non-engineers and make the documentation useful from a user prospective.

        And it's true I have to admit that many technical writers are bad writers or are lazy and produce crappy work. Because they can, everyone accepts that documentation sucks and no one reads it anyway so why bother?

        But there are also some excellent tech writers out there, people who work hard to produce well-written, clear documentation, help with testing and improve functional design, interface design, even sometimes writing error messages that have meaning. Usually though, the manual is getting slapped together in the last days before ship date, and we are busy mostly writing release notes documenting what we know is broken and any workarounds we might have to suggest, with promises to fix it asap, with an update or patch that will be coming soon. This is business as usual.

        Ideally software should be so good, with a logical interface, streamlined functional design and seamless performance so reliable that the user never needs to read a manual. This never has been and never will be reality though. Apple has gotten closer to that with some of it's recent products. A few other companies are getting there too. But I think broken software and glitchy rollouts are essentially unavoidable, from what I have seen in my 20+ years in the field. The bad documentation is just one symptom of the basic problems inherent in the process: complex technical work + changing requirements + deadlines = bad software, bad documentation, and constant updates.  

        •  Thanks for the deep background on the... (0+ / 0-)

          wonderful world of technical writing. Perhaps t'is true that "nobody reads it anyway."

          When in a pinch I'll resort to user's guides which (IMO) are given low priority by management.

          My good news is calling upon help-desk type resources gets questions readily answered. Maybe that's why a lot of technical writers take "bad writing" classes? Requires a lot more techs to work the phone lines than to write one user's guide.

          Nowadays, help videos have been a great resource and they are available 24/7.

          Entertaining too when IT departments are tasked with the production.

      •  That's a pretty sweeping damnation, (2+ / 0-)
        Recommended by:
        Notreadytobenice, VA gentlewoman

        Notreadytobenice.  I spent 15 years as a documentation specialist, as an independent contractor, and I was able to convince the companies that hired me to do so specifically because I was not a programmer, could not write code and had no desire to learn to do so.  I wrote manuals, quick reference guides, admin manuals and educational materials for users and administrators in simple English with step-by-step instructions that were easy to understand.  Help desks loved me.

        I had to meet with programmers and have them walk me through programs step-by-step while I made intentional mistakes and learned to back out of those mistakes or get around them.  Many times both of us became frustrated with the process, but better us than users.  Often I had to stop them and remind them to talk to me like a child because I didn't understand their language.  But it was worth our time and effort because it reduced the time and effort and stress the end users had to deal with.

        "In this world of sin and sorrow there is always something to be thankful for; as for me, I rejoice that I am not a Republican." - H. L. Mencken

        by SueDe on Mon Nov 04, 2013 at 11:25:52 AM PST

        [ Parent ]

Subscribe or Donate to support Daily Kos.

Click here for the mobile view of the site