[RFC] Bug 1616869 - Documentation overhaul specification

[adngdb]

This is a request for comments at the moment, I intend to evolve this into an actual specification based on feedback I will receive here and elsewhere.

Let's not discuss the form here, but only the content (form can be discussed in other specification PRs like #1562).

[flodolo]

I think a first step should be avoiding using role names that have an established connotation in Pontoon (contributor, administrator, manager).

Contributor -> Occasional developer? Administrator -> System Administrator? Manager -> Administrator

- **Contributor** — New developer looking to contribute to Pontoon's code base. Wants accessible setup and contributing documentation.
- **Administrator** — System administrator looking to host their own instance of Pontoon. Wants platform-specific setup documentation.
- **Localizer** — User of Pontoon looking to learn how to efficiently translate projects. Wants detailed features documentation.
- **Manager** — User of Pontoon looking to learn how to manage projects and locales. Wants detailed administration tasks documentation.
- **Core developer** — Core developer of Pontoon. Wants processes and technical documentation.

I'm also not clear what the expectation here is. I'd expect the specification to only have the agreed plan (i.e. the outcome of the discussion)?

[mathjazz]

First of all, I really like that you are working on this issue!

I don't see the need for distinction between two groups of developers (new and core). As a core developer, I still look into the Local setup and Contributing guidelines from time to time. I can also see (more senior) new developers jumping to technical documentation.

I'd call Managers "Project Managers", because that's how we call them. :-) I've seen the same terminology in other localization platforms, as well as "Localization managers".

[mathjazz]

As a small team I don't think we can afford spending time developing our own documentation solution, not even maintaining our own wiki deployment.

I'd go with a hosted documentation solution like ReadTheDocs, because it's the cheapest option. It's also not that much harder to click twice to edit than clicking once to edit the wiki page. :-)

[adngdb]

I'm also not clear what the expectation here is. I'd expect the specification to only have the agreed plan (i.e. the outcome of the discussion)?

Ultimately yes, that's what's going to happen, but I wanted to try to use this like Python does, as a "Request for comments". This PR should be a living thing, and the document will evolve with comments, until we reach a consensus.

[adngdb]

I'd go with a hosted documentation solution like ReadTheDocs, because it's the cheapest option. It's also not that much harder to click twice to edit than clicking once to edit the wiki page. :-)

I'm not sure I understand this. The problem with RTD is that documentation is in a git repo, on GitHub, and thus requires some technical skills to be able to edit it (a wiki is a much simpler tool to use for the average person). It's not really about the number of clicks, unless I misunderstood you? :curious:

[mathjazz]

I'm not sure I understand this. The problem with RTD is that documentation is in a git repo, on GitHub, and thus requires some technical skills to be able to edit it (a wiki is a much simpler tool to use for the average person). It's not really about the number of clicks, unless I misunderstood you? :curious:

There's "Edit on GitHub" link on top of each page on RTD, and once you get to GitHub, you just click the Edit (pencil) again which takes you to the editor: https://github.com/mozilla/pontoon/edit/master/docs/index.rst

It's harder than wiki, it's not WYSIWYG, and someone needs to merge the PR, but I think it's not a bad editing experience. In fact, a confirmation step before updating technical documentation is IMO a plus.

[Pike]

Leaving some personal opinions here:

I'd prefer for all docs to be in the pontoon repo.

I'm not sure how much impact localizing docs should have on our decision. I think it falls into the same bucket of "yes and" as localizing Pontoon itself.

We shouldn't pay too much attention on hosting. Anything that can be built can be put into an S3 bucket and served from there in the end.

There is the idea that PMs can write markdown and not restructured text. Support for markdown in Sphinx exists, but it doesn't cover all features, IIRC, https://www.sphinx-doc.org/en/master/usage/markdown.html.

[adngdb]

I'm not sure about Sphinx's support of Markdown, but in theory, Markdown supports HTML, so if a feature is not supported it should be possible to just build it with HTML markup, right? I'm think about tables for example, usually poorly supported in most markdown tools, but easy to set up with some good old HTML tags.

[Pike]

We should probably try on a dummy doc. Things I'd like to see tested are various cross references, indices, and search.

[mathjazz]

Not directly related, but I don't have a better place to dump it.

Nice docs on writing docs: https://documentation.divio.com/

Nice contributing guidelines: https://github.com/atom/atom/blob/master/CONTRIBUTING.md https://github.com/servo/servo/blob/master/CONTRIBUTING.md

Nice open source docs platform: https://docusaurus.io/

[srl295]

Should the buglink be #2214 ?

[mathjazz]

This patch has been stalled for a while.

Let's reopen when work continues.