Right so, there are several issues raised here and I don't really disagree with any of them - however, I'd hate to see anyone spend time on a project which might get superseded by development a little way down the line so rather than jump the gun let's see if we can come up with a plan of action.
First of all, is the docs editor I pushed today (the one we use 'in-house') sufficient for right now? It is a little flaky, but does (at least) give a preview of what docs will look like. By sufficient I mean 'able to be used by someone who wasn't involved in writing it (or have them sitting next to them)' which is essentially the situation we have in the office. If so, then hopefully that will serve for contributors needing to make small changes / add new docs for the time being (i.e. those adding engine features etc.). (I and my colleagues are in a slightly privileged position as I just send some notes to Elanor/Hanson and they sort out turning them into XML in-between their other responsibilities).
Looking to the future, then our current ideas are to present three types of documentation:
- Reference documentation for each piece of syntax - this will sit next to the syntax descriptions in the spec files that the refactored engine will (eventually) use. The idea being it will tell you precisely what the syntax will do, and what larger effects it has.
- Guides that explain how developers can use features to build functionality into their apps - we've started providing these, they are written in markdown.
- Lessons that explain how to solve specific problems - these use the ScreenSteps portal.
Indeed, in terms of guides, then we're hoping to provide a guide (providing examples of usage etc.) for each new feature area we add and, hopefully over time new guides for existing functionality in much the same way (thus replacing and updating the content of the User Guide).
Right now, of course, most of the information about how things work is contained in the XML dictionary entries and (as has been pointed out) these are not in as clean a state as would be ideal. Indeed, really they should be content-oriented and not display-oriented. However, this is partly a facet of legacy. The docs XML files have been processed a couple of times to improve structure although as they originally came from a source (a stack) that was display-oriented many (if not most) will still be in that style. As far as I can see (and if my memory serves correctly), the schema for the XML files in the contributors doc is not actually complete in that the docs processor (docs_builder in builder/) actually understands far more content-oriented tags than this suggests - the aim being that the XML files would gradually be migrated from display, to a content-oriented structure.
So, several questions come out of this:
- How many of the XML files are currently malformed? (I'm pretty sure it is not all - a cursory glance over the newly added ones today suggested that they were fine)
- If a substantial number, is it possible to write an automated tool to fix them?
- What is the current state of the XML schema as understood by the docs_builder and what is missing to help move docs to a more content-oriented style?
- What is the best approach with the current XML docs we have given we are intending to move the content to a different mechanism / location in the 'not-too-distant' future?
The last one of these is perhaps the most interesting as, to be fair, there is still much discussion to be had at the best approach. It would seem sensible that the docs (when they are written into the spec files) should be similar in style to something like HeaderDoc, JavaDoc or perhaps some sort of mark-down as that is easier to read than XML in its raw form and perhaps works a little better with text merging (of the sort git uses). However, what format should this documentation content be spat out in after the spec file is processed?
XML is still a worthy contender here as it is highly amenable to processing into other formats (the current dictionary XML is processed in three ways - for dictionary display in the IDE, for display in the online docs and into XML formatting objects for printing). Assuming XML still stands out as the best format for this 'intermediary' then making sure we should make sure we have a well enough defined schema (based around a content, not display oriented format) for it that is rich enough to give a good user-experience in all the forms the reference documentation is produced. Indeed, going down this road (with the idea that uniformity is good), it might be wise that the schema be rich enough to encompass release notes, guides and (potentially) lessons from ScreenSteps. (Maybe it would be better if these were a collection of related schemas).
Beyond that, a point was raised above about a style guide - then as far as I can recall we do have an internal one which those that write docs in the office reference. However, it has yet to make it up into the contributor's guide - I'll have to ask Hanson what the state of it is.
