Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
Malcolm Wallace wrote: In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up? Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do. I have tried writing documentation, but it seems that people do not know how to find, or use it. Navigating an API you do not know is hard. I'd like to signpost it better. From my experience, people are very good at learning patterns from examples, so a list of simple examples with increasing difficulty or a cookbook-style tutorial work very well. In comparison, learning from general descriptions is much harder and usually done by learning from examples anyway. A case in point might by my own reactive-banana library. http://haskell.org/haskellwiki/Reactive-banana I have extensive haddocks and many examples ranging from simple to complicated http://haskell.org/haskellwiki/Reactive-banana/Examples but so far, I never wrote a tutorial or introductory documentation. Curiously, instead of sending complaints, people send me suggestions and code. I interpret this as a sign that my library is easy to understand (if you know Applicative Functors, that is) even though a key part of the documentation is still missing. Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
I think a few examples can go a long way. I remembered seeing a lot of requests for examples in the results, so I went back and skimmed the spreadsheet. I found that 11 of the 34 responses under Library Documentation explicitly called out examples as desirable. Combined with Heinrich's experience, this sounds pretty promising to me. Cheers, Nick On 15 September 2011 05:24, Heinrich Apfelmus apfel...@quantentunnel.dewrote: Malcolm Wallace wrote: In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up? Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do. I have tried writing documentation, but it seems that people do not know how to find, or use it. Navigating an API you do not know is hard. I'd like to signpost it better. From my experience, people are very good at learning patterns from examples, so a list of simple examples with increasing difficulty or a cookbook-style tutorial work very well. In comparison, learning from general descriptions is much harder and usually done by learning from examples anyway. A case in point might by my own reactive-banana library. http://haskell.org/**haskellwiki/Reactive-bananahttp://haskell.org/haskellwiki/Reactive-banana I have extensive haddocks and many examples ranging from simple to complicated http://haskell.org/**haskellwiki/Reactive-banana/**Exampleshttp://haskell.org/haskellwiki/Reactive-banana/Examples but so far, I never wrote a tutorial or introductory documentation. Curiously, instead of sending complaints, people send me suggestions and code. I interpret this as a sign that my library is easy to understand (if you know Applicative Functors, that is) even though a key part of the documentation is still missing. Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com __**_ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/**mailman/listinfo/haskell-cafehttp://www.haskell.org/mailman/listinfo/haskell-cafe -- http://nickknowlson.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
Stephen Tetley wrote: Replying to someone's compliant in the first section: Malcolm Wallace and Colin Runciman's ICFP99 paper functioned well as a tutorial for HaXml when I used it - maybe it is a bit out of date now? HaXml is hardly a dire case. ... for the right audience. I guess the point is that the person complaining could not understand the existing documentation. Quote: This type of documentation may seem to “fall out” from a mathematically-oriented understanding of the library (such as haxml’s combinator scheme, or the concept of “lenses” in fclabels), but an application programmer does not have time to work through proofs of lens properties and then figure out what they might be good for in a program. Instead, the application programmer needs cookbook-style documentation to get something up and running, and then s/he can come to understand and make use of the underlying math. I'm not sure whether it's the job of library documentation to teach mathematical understanding, but cookbook-style examples seem very valuable to me. For instance, I think that the Happstack tutorial http://happstack.com/docs/crashcourse/index.html is excellent in this regard. (Personally, a good method for writing this kind of stuff is to assume that the reader has almost zero attention span. Then, I am forced to communicate the most useful points in the first few paragraphs, because my hypothetical reader probably won't read any further than that. Of course, the resulting text will be very useful to readers with a high attention span, too.) Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
On 09/12/11 17:48, Stephen Tetley wrote: Replying to someone's compliant in the first section: Malcolm Wallace and Colin Runciman's ICFP99 paper functioned well as a tutorial for HaXml when I used it - maybe it is a bit out of date now? HaXml is hardly a dire case. The paper is out-of-date, so it's worse than useless: you'll waste your time figuring out that it's wrong, and you still won't know how to do anything. There's not one single example anywhere that just shows you how to read or write a damned XML file. HaXml is what prompted me to start this page (bad language warning, if it ain't obvious): http://michael.orlitzky.com/articles/fuck_you.php If there were anything approaching a physical manifestation of HaXml, I would've strangled it. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
On 13 Sep 2011, at 18:59, Michael Orlitzky wrote: Malcolm Wallace and Colin Runciman's ICFP99 paper functioned well as a tutorial for HaXml when I used it - maybe it is a bit out of date now? HaXml is hardly a dire case. The paper is out-of-date, so it's worse than useless: you'll waste your time figuring out that it's wrong, and you still won't know how to do anything. There's not one single example anywhere that just shows you how to read or write a damned XML file. If there were anything approaching a physical manifestation of HaXml, I would've strangled it. I am the first to admit that HaXml's documentation is not as good as it could be, and I am sorry that you have had a bad experience. One thing I am puzzled about, is just how extremely difficult it must be, to click on Detailed documentation of the HaXml APIs from the HaXml homepage, look for a moment until you see Text.XML.HaXml.Parse in the list of modules, click on it, and find, right at the top of the page, a function that parses a String into an XML document tree. It is absolutely true that finding the reverse conversion (XML tree to String) is more obscure, being either the two-stage process of first using Text.XML.HaXml.Pretty to convert to a Doc, then Text.PrettyPrint.HughesPJ to render to a String; or alternatively the one-shot conversion in Text.XML.HaXml.Verbatim. Neither module name is as clear as it should be for a beginner, but I can't think of better ones. Plus, it requires some knowledge of the ecosystem, for instance that pretty-printing is a common technique for producing textual output. In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up? Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do. I have tried writing documentation, but it seems that people do not know how to find, or use it. Navigating an API you do not know is hard. I'd like to signpost it better. Regards, Malcolm ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
On 09/13/2011 05:15 PM, Malcolm Wallace wrote:
I am the first to admit that HaXml's documentation is not as good as
it could be, and I am sorry that you have had a bad experience.
Sorry for the tirade =) That was a while ago, but I definitely felt some
sympathy for the guy in the quote.
One thing I am puzzled about, is just how extremely difficult it must
be, to click on Detailed documentation of the HaXml APIs from the
HaXml homepage, look for a moment until you see
Text.XML.HaXml.Parse in the list of modules, click on it, and find,
right at the top of the page, a function that parses a String into an
XML document tree.
As someone who just wants to parse an XML file, here's what happens.
First, I click on the API docs. I'm presented with a list:
* Text
o XML
+ Text.XML.HaXml
# Text.XML.HaXml.ByteStringPP
# Text.XML.HaXml.Combinators
# DtdToHaskell
* Text.XML.HaXml.DtdToHaskell.Convert
* Text.XML.HaXml.DtdToHaskell.Instance
* Text.XML.HaXml.DtdToHaskell.TypeDef
# Text.XML.HaXml.Escape
# Html
* Text.XML.HaXml.Html.Generate
* Text.XML.HaXml.Html.Parse
* Text.XML.HaXml.Html.ParseLazy
* Text.XML.HaXml.Html.Pretty
# Text.XML.HaXml.Lex
# Text.XML.HaXml.Namespaces
# Text.XML.HaXml.OneOfN
# Text.XML.HaXml.Parse
# Text.XML.HaXml.ParseLazy
# Text.XML.HaXml.Posn
# Text.XML.HaXml.Pretty
# Text.XML.HaXml.SAX
# Schema
* Text.XML.HaXml.Schema.Environment
* Text.XML.HaXml.Schema.HaskellTypeModel
* Text.XML.HaXml.Schema.NameConversion
* Text.XML.HaXml.Schema.Parse
* Text.XML.HaXml.Schema.PrettyHaskell
* Text.XML.HaXml.Schema.PrimitiveTypes
* Text.XML.HaXml.Schema.Schema
* Text.XML.HaXml.Schema.TypeConversion
* Text.XML.HaXml.Schema.XSDTypeModel
# Text.XML.HaXml.ShowXmlLazy
# Text.XML.HaXml.TypeMapping
# Text.XML.HaXml.Types
# Text.XML.HaXml.Util
# Text.XML.HaXml.Validate
# Text.XML.HaXml.Verbatim
# Text.XML.HaXml.Wrappers
# Text.XML.HaXml.XmlContent
* Text.XML.HaXml.XmlContent.Haskell
* Text.XML.HaXml.XmlContent.Parser
# Xtract
* Text.XML.HaXml.Xtract.Combinators
* Text.XML.HaXml.Xtract.Lex
* Text.XML.HaXml.Xtract.Parse
Jesus! /You/ know that I want to look in Text.XML.HaXml.Parse, but /I/
don't. Let's say I choose the first link: Text.XML.HaXml. It's a list of
modules, along with their documentation. All blank! Hitting the back button.
The first thing I notice is that there seems to be specialized parser
modules for different content types, e.g. Text.XML.HaXml.Html.Parse.
Maybe I want Text.XML.HaXml.Schema.Parse? I mean, I want to parse
something with a schema, right? Nope, it's for parsing XSDs.
How about Text.XML.HaXml.Util? This looks right...
Only a small module containing some helper functions to extract xml
content - I would have added this to Types but I've put it into an
additional module - to avoid circular references (Verbatim - Types)
and it's got a function called docContent which is supposed to Get the
main element of the document... Great. Its type is,
docContent :: i - Document i - Content i
so now, to have any hope of using this function (or figure out that I'm
in the wrong place entirely), I have to go figure out what those types
are. Document has one constructor,
Document Prolog (SymTab EntityDef) (Element i) [Misc]
which leads me to,
Prolog (Maybe XMLDecl) [Misc] (Maybe DocTypeDecl) [Misc]
XMLDecl VersionInfo (Maybe EncodingDecl) (Maybe SDDecl)
type VersionInfo = String
newtype EncodingDecl = EncodingDecl String
type SDDecl = Bool
data Misc = Comment Comment | PI ProcessingInstruction
type Comment = String
type ProcessingInstruction = (PITarget, String)
type PITarget = String
data DocTypeDecl = DTD QName (Maybe ExternalID) [MarkupDecl]
data QName = N Name | QN Namespace Name
type Name = String
data Namespace = Namespace {nsPrefix :: String, nsURI :: String}
data ExternalID = SYSTEM
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
On Sep 13, 2011, at 7:38 PM, Michael Orlitzky wrote: One thing I am puzzled about, is just how extremely difficult it must be, to click on Detailed documentation of the HaXml APIs from the HaXml homepage, look for a moment until you see Text.XML.HaXml.Parse in the list of modules, click on it, and find, right at the top of the page, a function that parses a String into an XML document tree. As someone who just wants to parse an XML file, here's what happens. First, I click on the API docs. I'm presented with a list: * Text o XML + Text.XML.HaXml # Text.XML.HaXml.ByteStringPP # Text.XML.HaXml.Combinators # DtdToHaskell * Text.XML.HaXml.DtdToHaskell.Convert snip I think you make an important point here. As a beginner myself, I am often surprised by the sparse first impression of modules that hackage offers. To a beginner, the one sentence introduction often using domain-specific language is thwarting. Compare hackage to CPAN or Sphinx documentation which present pages of examples covering all programmer-visible interfaces and the difference is clear: hackage is a module repository first and a documentation browser last. Cheers, M ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
I would appreciate is a few paragraphs in the toplevel haddock page or module that describe the general architecture and layout of the modules, as well as the typical entry points. Since the module system doesn't have a notion of private modules and it's common to re-export symbols, it can be unclear where to start, which modules to look at, and why it is the author chose that particular decomposition for the functions. Overall design and architecture is hard to get out of the code. I think the same goes for each module. It's frustrating when I want to figure out how something works, and each module just has a giant chunk of license copy-paste at the top. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
Replying to someone's compliant in the first section: Malcolm Wallace and Colin Runciman's ICFP99 paper functioned well as a tutorial for HaXml when I used it - maybe it is a bit out of date now? HaXml is hardly a dire case. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
