Consolidate developer documentation?
A recent discussion with @nh2 and @phadej reminded me of the rather fragmented state of our developer documentation. Currently GHC's developer documentation is spread across a number of places:
- various namespaces of the ghc/ghc> wiki (e.g. Commentary, Working Conventions)
- the users guide (e.g. "Care and feeding of the users guide")
- various bits of in-tree documentation (e.g.
hadrian/doc)
In particular while there is a great deal of prose on the Wiki, it has proven to be quite hard to keep up-to-date with on-going changes in the source tree. A few months ago we discussed the prospect of consolidating this documentation into a single developer guide (similar to the user guide). @simonpj and @rae both agreed that the idea sounded plausible. However, there are a few details to be worked out:
- how do we avoid the MR workflow becoming an impediment to improving documentation?
- how do we balance the desire to ensure the accuracy of the migrated content against the effort needed to do so?