Also sprach Andrew Halberstadt:
On Fri, Jun 16, 2017 at 4:33 AM, Sylvestre Ledru
<sylves...@mozilla.com> wrote:
As most of the people don't like to spend time writing docs, I am a
bit concerned that using in-tree docs with our "heavy" review process
(bug, reviewers, etc) will even decrease our contributions to the doc
(instead of the MDN wiki where it is quick to contribute).
I suspect overall you're right, but for me personally the opposite
is true. I'm much more likely to remember to update the docs for a
breaking change I make if they live somewhere near the source, than I
am to remember to hunt down all the appropriate wiki/mdn pages.
I tend to agree with both points of view: I’m more likely to remember
updating documentation when I grep through the source to find references
to what I’m patching, but perhaps less inclined to file separate bugs
to fix up existing documentation.
However, what concerns me much more than ease of editing is
discoverability. MDN is well-indexed and highly ranked by search
engines and has hyperlinks, making it (tolerably) easy to find what
information it holds on any given subject.
How do we expose publicly-intended non-web API documentation from the
tree and make it discoverable by search engines?
Awhile back I briefly looked into whether DXR or SF could support some
sort of "Edit" functionality a la Github, for quick things like typo
fixes and doc edits. It could potentially create a mozreview request
(or conduit request) on behalf of the user. I'd love if we could push
on that, maybe this would be a good excuse.
Our current workflow uses Bugzilla bugs as the central focal point.
I think there would either have to be a change to this policy, or an
exception to this rule for documentation for that to work.
I am otherwise in full agreement that it would be desireable to have a
less “heavy”, as Sylvestre describes it, process.
_______________________________________________
dev-builds mailing list
dev-builds@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-builds
