Pontoon: document home page setting in profile
Closed this issue · 8 comments
I'm fine with all of the above and a little torn between bug (bullet point 1) and PR (bullet point 3).
I like bug, because that's where it usually becomes obvious if we need to update the docs or not, so it communicates the need sooner. OTOH, the UX could change as we develop the patch, so we risk writing the docs too early.
@flodolo @Pike @adngdb thoughts?
Anyhow, at the end of the day we should document it in https://github.com/mozilla/pontoon/blob/master/CONTRIBUTING.rst.
I like bug, because that's where it usually becomes obvious if we need to update the docs or not, so it communicates the need sooner.
I realized that we started doing this: l10n-docs-added and l10n-docs-needed.
It definitely requires help from devs, it's hard for me to tell if a bug actually has UI impact, and they might slip.
OTOH, the UX could change as we develop the patch, so we risk writing the docs too early.
That's relatively easy to fix: we start writing docs once that's merged.
That's relatively easy to fix: we start writing docs once that's merged.
Or we fix the docs when we make changes, a little bit like we change unit tests when we change the code. :-)
The bothering thing here to me is that documentation is separated from code, which means you have to update two repositories. Not that I have a better proposal, but it requires some education for devs (including me! ) to remember that there's documentation to update somewhere else. Also, we can't really block merging something because the doc is missing, or at least, it's difficult.
l10n-docs-needed looks like a pretty solution to me. We should have an easy way of tracking those though, maybe a link in the channel's topic?
Or we fix the docs when we make changes, a little bit like we change unit tests when we change the code. :-)
The key difference is that we get an automated reminder from Travis in case we forget to update unit tests. :)
which means you have to update two repositories.
You don't necessarily need to, you just need to flag the PR/bug so that one of the PM (likely me) takes care of it.
P.S. I have saved searches for both keywords, e.g. for l10n-docs-needed
Hah, I wasn't aware that you were "in charge" of writing those docs. Much easier in that case! :P Thanks Flod!
To be clear, I don't plan to discourage any dev willing to write their own doc, quite the contrary :)
I guessed so, hence the quotes around "in charge". 😄
[/spam]