[Development] Qt Coding Guidelines
edward.welbourne at theqtcompany.com
Fri Mar 18 10:55:24 CET 2016
>>> The question is, can/should we get the HTML output of these documents
>>> published somewhere, for ease of access?
All the HTML generated from QDoc in all of our code should be visible in
some public way. This would just be one more page of that.
>>> Do they need their own repository to get them updated daily?
There are also "snapshot" versions of the HTML available , that
change often, as well as the per-release official versions.
It remains that this document is expected to be quite stable, so there
would be some sense to having a stable URL to which we routinely copy
the new version once a change to the source has been accepted. The
effort involved would be minor, I must suppose.
>> What's wrong with reading them as plain text?
Putting them in the source lets developers read them as plain text.
As we're fluent in QDoc format, that works for us.
The rest of the world likes the web browsing presentation better.
(Also: following links - even we like the web better for that.)
In particular, when someone on a team is trying to persuade the rest of
the team to adopt our style, that team isn't necessarily all coding with
Qt or using QDoc; so it's important to give them a nice reading
experience as they learn about our style. *After* we've brought them
round to our way of seeing things, we might coax them into learning QDoc
as well, but we need to make it easy for them to agree to the first
step, if we're to have a chance at that.
> What's the point at using a markup format then?
Markup plays well with code review (line-structured, plain text) but can
be turned into a form that displays nicely (good for advocacy).
More information about the Development