doc: dev guide updates

doc/developer-guide.md

@@ -14,8 +14,8 @@ tr {
 <!-- | hledger.org&nbsp;&nbsp; | [combined release notes](release notes), [pre-compiled binaries](download) | -->
 <!-- [web ui demo](http://demo.hledger.org/register?q=inacct%3Aassets%3Abank%3Achecking+sym%3A\%24) -->
 |-------------------------|----------------------------------------------------------------------------|
-| IRC                     | Join [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) |
+| IRC                     | Join [#hledger](http://hledger.org/irc) ([chat log](http://ircbrowse.net/browse/hledger); see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) |
-| Mail list               | [list.hledger.org](http://hledger.org/list) ([Gmane](http://dir.gmane.org/gmane.comp.finance.ledger.hledger)) |
+| Mail list               | [list.hledger.org](http://list.hledger.org) ([Gmane](http://dir.gmane.org/gmane.comp.finance.ledger.hledger)) |
 | Twitter                 | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), <a href="https://twitter.com/ledgertips">@LedgerTips</a> |
 | hledger-web demo&nbsp;&nbsp;        | [demo.hledger.org](http://demo.hledger.org) |
 | Trello                  | [planning board](http://hledger.org/trello) |
@@ -96,26 +96,18 @@ The hledger project aims to produce:
 
 ### Documentation
 
-Project documentation appears in many places:
+Project documentation lives in a number of places:
 
-- website
+- `doc/*.md` and `doc/site/*.md` form the hledger.org website, which is generated with hakyll[-std] and pandoc
-- user manual
+- haddock documentation in the code appears on Hackage
-- developer guide
+- short blurbs: cabal files, module headers, HCAR, GSOC project, ..
-- code documentation: haddock
+- `doc/notes.org` has some old developer notes
-- various developer reports
+- developer reports (profiles, benchmarks, coverage..) in doc/profs, sometimes published at hledger.org/profs
-- developer notes outline
-- blurbs: in cabal files, module headers, google project, repo message of the day..
-
-For most of hledger's history, documentation was primarily (all capitals) markdown files in the source code repository. This was processed by pandoc, hakyll or yst to generate a static website.
-
-As of 2014/2, hledger.org is a wiki, and most docs are maintained as wiki pages.
-Some, particularly the user manual and release notes, still exist in the main source repo as well.
-These should probably not be updated directly, instead they are copied from the wiki before each release.
 
 ### Code
 
-The hledger repo is hosted on Github, at http://github.com/simonmichael/hledger.
+The hledger repo is hosted on Github, at <http://github.com/simonmichael/hledger>.
-You can also jump there via hledger.org/code[/commits] or code.hledger.org[/commits].
+You can also jump there via `code.hledger.org[/commits]`.
 
 ### Quality control
 
@@ -162,7 +154,7 @@ Here's the original [proposal](http://article.gmane.org/gmane.comp.finance.ledge
 There are two core cabal packages:
 
 **[hledger-lib](http://hackage.haskell.org/package/hledger-lib)** - data model, parsing, manipulation, standard reports
-([github](https://github.com/simonmichael/hledger/tree/master/hledger-lib))\\
+([github](https://github.com/simonmichael/hledger/tree/master/hledger-lib))\
 **[hledger](http://hackage.haskell.org/package/hledger)** - command line interface, reusable cli options & helpers
 ([github](https://github.com/simonmichael/hledger/tree/master/hledger))
 
@@ -307,26 +299,26 @@ Here are some tips to help you get productive on the hledger project.
 
 ### Suggest enhancements
 
-Suggestions and feature requests are easy to make. They are welcome feedback, 
+Suggestions and feature requests (aka wishes) are easy to make, and can be valuable,
-but we don't want them to pile up and
+but we don't want them to pile up ad infinitum and obscure bugs and
-obscure bugs and other developer priorities, so we try manage them a. with discussion
+other developer priorities. Before opening a github issue, consider:
-and b. optionally as cards on a trello board.
-The current recommendation is
 
-1. **discuss/research first**\\
+1. Perhaps discussion is most appropriate at this stage ?
-   Is your wish already on the [trello wishlist/planning board](http://hledger.org/trello)
+   [#hledger](irc://irc.freenode.net/#ledger) or the
-   or [bug tracker](http://hledger.org/bugs) ?\\
+   [mail list](http://list.hledger.org) are excellent places for this.
-   In any case, perhaps discuss it on [irc](irc://irc.freenode.net/#ledger) or the [mail list](http://hledger.org/list) first ?
+   Both are archived, so the idea won't be lost.
+2. We have a collection of enhancement ideas on the
+   [trello planning board](http://hledger.org/trello).
+   Perhaps your idea is already there, or you can add it ?
+3. We have bug reports and more wishes in the [bug tracker](http:///bugs.hledger.org).
+   Is your idea already there ?
 
-2. **wishes are best stored on trello**\\
+When a wish does land in the bug tracker, it gets the WISH label,
-   Is it a problem with the current released product ? report in the [bug tracker](http://hledger.org/bugs)\\
+and the default view given by [bugs.hledger.org](http://bugs.hledger.org) excludes these.
-   Is it a feature idea or wish ? add a card on the [trello board](http://hledger.org/trello), if needed
-
-But do what you think best. When a wish does land in the bug tracker, it gets the WISH label.
 
 ### Report problems
 
-- check for related issues in the [bug tracker](http://hledger.org/bugs) or in the [mail list archive](http://hledger.org/list)
+- check for related issues in the [bug tracker](http:///bugs.hledger.org) or in the [mail list archive](http://list.hledger.org)
 - discuss/confirm the issue on irc or list
 - report new issues in the bug tracker
 <!-- - test and share problem journal snippets at paste . hledger.org -->
@@ -343,12 +335,12 @@ But do what you think best. When a wish does land in the bug tracker, it gets th
 
 ### Help with bug tracking
 
-- get to know the [bug tracker](http://hledger.org/bugs) and its contents
+- get to know the [bug tracker](http://bugs.hledger.org) and its contents
 - research and update issues
-- some convenient url shortcuts:\\
+- some convenient url shortcuts:\
-  [`hledger.org/bugs`](http://hledger.org/bugs)\\
+  [`bugs.hledger.org`](http://bugs.hledger.org)\
-  [`hledger.org/bugs/new`](http://hledger.org/bugs/new)\\
+  [`bugs.hledger.org/new`](http://bugs.hledger.org/new)\
-  `hledger.org/bugs/N`
+  `bugs.hledger.org/N`
 
 ### Set up for development
 
@@ -379,12 +371,12 @@ But do what you think best. When a wish does land in the bug tracker, it gets th
     Note this executable will not be as optimised as the normal cabal build, and has the "dev" suffix
     as a reminder of this.
 
-9. try auto-building with sp:
+<!-- 9. try auto-building with sp: -->
 
-        make auto   # or autoweb
+<!--         make auto   # or autoweb -->
 
-    You'll need to follow the instructions to install `sp`.
+<!--     You'll need to follow the instructions to install `sp`. -->
-    This is how I do most hledger development. It will recompile whenever you save changes to source files.
+<!--     This is how I do most hledger development. It will recompile whenever you save changes to source files. -->
 
 ### Get your changes accepted