User Documentation

[romanofski]

Well, for a 1.0 release we also need user facing documentation. Question is, what to we want to provide for our first release:

• user guide
• reference

in what format:

• man page
• HTML

[romanofski]

I'm realising, that we might be able to leverage haddock for the reference. Wouldn't we need to put in a reference for all the configuration options we have? In that case, we could possibly use docstrings from haddock for each configuration option to describe what they're for or what they do. That way we can update it easily next to our code, without having the problem that the documentation goes out of sync.

[romanofski]

I think I'm picking this up next. I'll have a look whether we can easily hook this into the UI as well. My current idea would be to:

• Write the user docs in asciidoc.
• The reference documentation stays Haddock, but will have to be improved.

What I'm not so sure about, but want to investigate:

• The sections/chapters(?) of the user documentation can be exported as man pages.
• Those man pages can be referenced/looked up with an internal dictionary/hashmap to show user docs inside the Purebred UI. Perhaps just using the Brick.suspendAndresumewith man may just do the trick ...

[frasertweedale]

yeah, running man seems fine to me. Dunno where that would leave Windows users but until someone asks I wouldn't bother :)

[romanofski]

Actually thinking more about this... perhaps there might be a point using a browser for the docs. This could be either a console browser or a firefox or whatever. The benefit of this would be that it's easier to deliver the docs (either offline or online) and we can link to the haddock reference as well.

[frasertweedale]

Sure, build the docs and publish somewhere, and optionally package them for local installation. Whatever you prefer mate. It's not even either/or TBH. But whatever you want to deliver will be better than what we currently have (nothing!)

[romanofski]

One itch I'd like to scratch is some form of referencing our current configuration. The typical thing which happens with documentation is that the reference basically duplicates what we have in code and therefore renders the documentation less useful.

Haddock is great of providing the base for like developer documentation, but it would be less useful for using it as a user manual. Our target isn't novice users anyways, but it would still be good to provide some form of go to steps for the intermediates who can navigate their way through Haskell.

I wrote this little tool (purebred-dump-config) as a proof of concept which can basically dump our configuration in order to include it in the manual. I've used the show instances to get a feel for how it might work and obviously at the moment it's very verbose. It currently is also included as a source file. I wonder if it could dump more asciidoc compliant markup, so we would know if references are broken when the source file changes.

[romanofski]

Meh.. Looking at what we already have available in our haddock I think pretty printing the config is most likely overkill. Instead what I'll focus on is to use the tool to dump our keybindings similarly to what we have in our help view. In fact I might be able to use (almost) the same code ...