How to develop user manuals?

Asked

Viewed 13,259 times

11

I came across a situation here that prompted me to look for some software that would allow me to create a well done user manual.

What happens is that I was tasked with developing the system user manual that we have here for a request from a client. The system is giant and if I were to do in hand a user manual would last for months.

So I decided to look for some software that automates some part of this work to help me.

Well, I found some software that helps, almost all are paid, there are some free.

It’s them: Helpndoc, Dr.Explain, Doxygen, Ckeditor and Help&manual. Some provide Apis for integration with some languages.

My doubts are:

  • How can I develop a good user manual?
  • Is there any standard or pattern that should be followed when making a manual?
software-engineering documentation
  • 1

    All are good, test all and see which one suits you best, develop a manual, depends a lot on the complexity and public of the manual, and the standard would be with a good Portuguese and follow ABNT :D kkkk standards

  • 1

    @Rod, have you ever used any of them? KKKKKK, that’s a very important detail!

  • 2

    I used only the Ckeditor for editing texts, rs

  • @The documentation tag has two links in English that can be a starting point. I will update this Wiki according to the responses that appear here.

  • @Rod I found the Ckeditor very basic... I’m testing the Helpndoc, and apparently it’s quite complete.

  • @Gypsy Rhyming Mendez, Porxa cara, thanks a lot, I’ll give a read!

  • 3

    If it is a software of use via WEB it would be interesting to go for documentation in videos first, instead of texts. A quicker way to make a manual is to use the FAQ scheme before going documenting steps. Often the steps depend on understanding legislation or internal processes of the company what will need deepening that have nothing to do with the software itself.

Show 2 more comments

3 answers

13


So you don’t have to worry so much about formatting, and be able to focus on writing the content of the documentation, I suggest these tools:

  • Using Latex you take advantage of an existing formatting template and generate a high quality PDF. An example of excellent documentation done in Latex: manual / manual source code
  • Using the Markdown syntax you can create HTML documentation.
  • Git will help you keep track of versions of your documentation.
  • A good text editor, such as Sublime Text, which has plugins to help you use the above tools.

7

Software that helps make user manuals are common to help produce any written content. It will be mainly a word processor and eventually others who can help illustrate the text. There’s nothing to help you write the user manual. Eventually one can use some software to put in a specific format that can be read by some standard software, but they will not do the work of months turn into days, it will only do a finish after the manual is ready.

The other software described in the question helps document API, so we’re not talking user manual. They help a little, but it’s basically formatting, the API documentation should be done carefully and this will be responsible for almost all the time taken.

I can only recommend testing them all and come to your conclusion which helps you best. Random people on the Internet won’t be able to tell you what’s good for you.

I believe that other aspects do not fit here in Sopt.

  • I didn’t mean that these softwares would do all the documentation for me. What they help is what you said: the finish. This help in finishing makes all the difference when it comes to making a manual, because this is where the most criticism happens and also where it takes longer to finish. If I expressed myself badly about this, I’m sorry.

  • 1

    No, it doesn’t. What makes the difference is what you put in it. I try to have a bad content well formatted and another good bad format and see which help more. This finish takes minimal time, help is always welcome but does not give much gain near all the work that is needed.

3

You can use Text Editor templates to format your document.

If you master, you can use HTML with a CSS Framework and develop a Web manual.

You can develop a Latex manual (also interested in mastering). The finish is good and is easy to do after mastering the language.

You can create video tutorials on the system.

You can use a presentation editor with a template to make everything standard. You can even combine it with videos.

You can use publishing software like Scribus to help you finish.

Browser other questions tagged software-engineering documentation

You are not signed in. Login or sign up in order to post.