Haddock documentation doesn't help new users

[edom]

There is too much Haddock documentation for MFlow. The documentation tries to feed the user too much information at once. The documentation doesn't help new users quickly figure out how they can use this awesome package. This is made even worse by the numerous typos scattered in the documentation. These typos make the package seem unfit for real-world usage.

New users interested in MFlow only care about how they can use it. There is no doubt that it is built upon a great idea, but they haven't yet had the understanding needed to appreciate it.

People might adopt MFlow much more eagerly if we reduce friction for new users. We can do this by empathizing with our would-be users while we write our documentation. We can do this by seeing things from their point of view and anticipating their problems.

A separate tutorial somewhere in the Internet isn't enough; the Haddock documentation itself has to guide the new user because that documentation is what the user expects to read first after installing a package.

[agocorona]

I only can say that you are right. Sorry for the typos, I´m slightly dyslexic and it is a torture for me to fix these misspellings, besides I´m not a native english speaker.

have you seen http://mflowdemo.herokuapp.com?

It is based on examples. It is where I tried to supplement the information that is absent from the Haddock documentation.

[edom]

Sorry, I didn't know about your dyslexia. Yes, I have seen the page at herokuapp. May I suggest the following about that website?

1. Increase the font size
2. Reduce the amount of text in the front page

This may sound strange, but how about writing less documentation? What do you think?

[agocorona]

It s a 10% dyslexia and a 90% pure lazyness...

I understand your point. Too much packed information is not helpful. I
also hate to spend time formatting web pages.

I thank you for your appreciation of MFlow. I know that the MFlow concept
will win since it is the right thing.

Now I´m busy with other projects and I have not much time to change the
design. hplayground is the client side of MFlow. do you know it?

tryplayg.herokuapp.com

In the medium term I will integrate both.

2014-10-26 20:47 GMT+01:00 Erik Dominikus notifications@github.com:

Sorry, I didn't know about your dyslexia. Yes, I have seen the page at
herokuapp. May I suggest the following about that website?

1. Increase the font size
2. Reduce the amount of text in the front page

This may sound strange, but how about writing less documentation? What do
you think?

—
Reply to this email directly or view it on GitHub
#56 (comment).

Alberto.