Android Tutorial Writing good documentation

Discussion in 'Tutorials & Examples' started by HotShoe, Jun 2, 2015.

  1. HotShoe

    HotShoe Well-Known Member Licensed User

    When you finally finish your gee wiz killer app and want to write the documentation for it explaining how to use it, there are some things you need to consider.

    First, find someone with no technical skills or knowledge of computers. Someone that knows how to write well and is good at talking to people, then have then do the writing. Tech folks just don't do well trying to write docs as a rule. Don't believe me though, just read any docs written by Linux or android guys.

    Next, give your writer the app and a device and explain what it does and why. Show them how the app works and let them play with it for a week or two to get the feel of it. This also doubles as a last chance Beta test, which is never a bad thing.

    If you don't have a writer handy that is not a technological idiot, then you may have to do it yourself. In that case, forget about trying to impress anyone with all of the big words and algorithm tech talk. No one cares! They just need you to explain how to make the damned thing work the way they want as simply and as easy to understand as possible. Make sure to keep it basic and avoid using impressive tech phrases about the underlying code.

    Just approach it from a users point of view, like you've never seen the app before. Start at the setup if any, and go step by step in the order they need to do things to get the app up and running.

    Then you can go through the features and how to use them, and any options that may be available. Think of the entire process as if you are explaining the app to a 6 year old. Then give the printed docs to 3 or 4 people to read through and tell you what they don't understand. Tell them to be brutally honest, and don't take any of the comments personally. It's the docs they are talking about, not you.

    The trend now days in software like Android apps is to have no or very little documentation. I think this is a huge mistake to make. Where is a user supposed to go to figure out how to make it work without good docs? Their first stop is probably to the Play store where they will immediately rate your shiny new app low, just out of frustration.

    You can incorporate docs into the app in many different ways. From text files to HTML or PDF files. The more complex your app is, the greater the need for good, clear cut documentation. I encourage everyone to include docs of some kind in your apps, even if you feel it is so self explanatory that even a 3 year old could figure it out.

    --- Jem
     
    NJDude, MikeH, Troberg and 1 other person like this.
  2. Troberg

    Troberg Well-Known Member Licensed User

    Also, make sure you proof read the docs for correctness.

    I'm currently trying to understand how to reprogram the light automatics on my car, and I've think I've read the manual instructions 10 times, and the only thing that's clear is that whoever wrote it had now idea whatsoever about how it worked...

    Sadly, Google discourages docs and instructions in their guidelines, instead encouraging a "play to learn" method. This works for some people, but there are a lot of people out there who are afraid to try anything they are not clearly instructed to do.
     
Loading...