• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

B&S: What to include into user documentation

 
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi,

what topics do you or did you provide for your user documentation?

I think to include the following issues (this is not my table of contents):

  • 1. Installation (submission jar file, runme jar, ...)
  • 2. Set Environment (JAVA_HOME, path, working directory, ...)
  • 3. How to start Client, Server and Standalone (java -jar runme.jar alone, ...)
  • 4. Set Properties for Client, Server and Standalone
  • 5. How to use the application (Booking, Searching, ...)


  • You see one could cover lots of topics, but honestly I don't know whether this is really necessary since it's a user guide and not an installation guide.

    I doubt whether a user really needs to know about 1., 2. and 3.

    Any hints ?

    Regards,
    Darya
     
    Ranch Hand
    Posts: 357
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    I doubt whether a user really needs to know about 1., 2. and 3.


    I left out 1 and 2, but included 3. But since I had online documentation, that was already a bit pointless. (The user could only read how to start the application if (s)he managed to start the application ).

    I got the full score for documentation, so I guess 1 and 2 is not really necessary.

    Frans.
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    Hi Frans,

    Having the information on how to start the application when you already started the application is of course a little bit beastly

    However your full score is always a good argument .

    To me, I miss somtehing like a installation guide. The list items 1. and 2. also don't belong into a user guide. So there will be nothing like a installation guide in my submission jar file.

    Strange isn't it ?

    Regards,
    Darya
     
    Frans Janssen
    Ranch Hand
    Posts: 357
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Having the information on how to start the application when you already started the application is of course a little bit beastly

    However your full score is always a good argument .


    Of course, I might have done too much. Probably it would still have been OK if I left out the help on start-up.

    To me, I miss somtehing like a installation guide. The list items 1. and 2. also don't belong into a user guide. So there will be nothing like a installation guide in my submission jar file.

    Strange isn't it ?


    I guess we can assume that the assessor knows how to install our software. After all, the instructions already determine how our submission can be installed.

    Frans.
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    So, if no one else complains I will describe list items 3., 4. and 5. in my userguide.txt

    Regards,
    Darya
     
    I'm thinking about a new battle cry. Maybe "Not in the face! Not in the face!" Any thoughts tiny ad?
    a bit of art, as a gift, the permaculture playing cards
    https://gardener-gift.com
    reply
      Bookmark Topic Watch Topic
    • New Topic