[RFC] Bug 1616869 - Documentation overhaul specification #1570

adngdb · 2020-02-20T16:00:44Z

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 · 2020-02-20T16:34:04Z

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 · 2020-02-21T11:00:44Z

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 · 2020-02-21T11:12:11Z

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 · 2020-02-25T10:29:36Z

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 · 2020-02-25T10:31:42Z

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 · 2020-02-26T15:46:36Z

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.

gueroJeff · 2020-02-26T17:19:09Z

specs/0102-documentation-overhaul.md

+**Cons**
+
+- Two distinct documentations to maintain, which is more difficult.
+- There might be confusion about what to put where.


We'll need to define criteria, for sure.

gueroJeff · 2020-02-26T17:19:49Z

specs/0102-documentation-overhaul.md

+**Pros**
+
+- Hosted with Pontoon's code base, allowing to enforce documentation updates along with code changes.
+- Localization is technically possible, but I don't know how difficult it would be.


Actually performing localization or are we talking about multilingual publishing, or both?

This is about the technical side, enabling localization. I didn't consider the translation work in this document.

gueroJeff · 2020-02-26T17:20:18Z

specs/0102-documentation-overhaul.md

+
+**Cons**
+
+- Contributing to the documentation is difficult as it requires making a pull request on GitHub.


That's the current barrier to entry for localizer-documentation too.

gueroJeff · 2020-02-26T17:21:38Z

specs/0102-documentation-overhaul.md

+- Very easy to edit, by anyone interested in doing so.
+- Some wikis support content localization out of the box.
+
+**Cons**


Moderation may add overhead too.

Pike · 2020-05-06T08:00:37Z

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 · 2020-05-10T09:28:50Z

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 · 2020-07-01T09:42:54Z

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

mathjazz · 2020-08-12T21:49:31Z

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/

…names.

mathjazz · 2021-03-17T01:38:30Z

specs/0104-documentation-overhaul.md

+
+## Maintenance
+
+TBD


I wonder if there's something we can do to "enforce documentation updates along with code updates".

Something automated, something like documentation coverage.

What do we exactly expect from such software? e.g. print what parts of the documentation should be updated in a PR?

Maybe we should involve more people in the review process, e.g. ask a localizer/project manager to check the documentation about a feature/bugfix (?)

Pike · 2021-03-17T12:55:09Z

specs/0104-documentation-overhaul.md

+
+## Where to host
+
+Documentation is hosted in a dedicated section within Pontoon app (`/docs`) and built on each deployment.


This might require changes to how we deploy. I wouldn't like the idea to use a django app to host static content, and the whitenoise middleware isn't set up to handle more than /static, and it might not be the right choice to fiddle that in. Whitenoise does a lot of start-up work that might just bloat our runtime.

Pike · 2021-03-17T12:56:14Z

specs/0104-documentation-overhaul.md

+
+## What format to use
+
+Documentation is writen using the Markdown syntax.


I think we should be more specific here on the toolchain.

Do we plan to use a static site generator?

Pike · 2021-03-17T13:11:54Z

specs/0104-documentation-overhaul.md

+
+- **Localizer** — User of Pontoon wanting to learn how to efficiently translate and review projects. Looks for detailed feature documentation.
+- **Administrator** — User of Pontoon wanting to learn how to manage projects and teams. Looks for detailed administration tasks documentation.
+- **Project Owner** — Anyone wanting to make their project translated into several languages. Looks for internationalization and deployment documentation.


I'm not sure we should include this target audience. If I understand this correctly, I'd assume this to be very specific to each org deploying Pontoon.

Also, is this deploying Pontoon or projects localized with Pontoon?

This covers deploying Pontoon as well as prerequisites on the side of the project to be localized (i.e. information about supported l10n frameworks, file formats and VCS systems, required access, file and folder structure):

https://mozilla-pontoon.readthedocs.io/en/latest/user/localizing-your-projects.html (without Adding a new project section, which is Administrator)

https://mozilla-pontoon.readthedocs.io/en/latest/admin/deployment.html

https://mozilla-pontoon.readthedocs.io/en/latest/admin/maintenance.html

flodolo

I think this is still a bit too vague.

We want to use Markdown, great. How do we convert it to static HTML? How do we deal with images?
Will the solution support search? That's a blocker.

I'm OK with having all docs in one place, but not in exposing them together. Localizers are interested in user docs, not the rest, so they shouldn't have to navigate through the entire documentation, or be exposed to it.

Side note: I don't think there's anything preventing us from deploying parts of the documentation to GH pages, like we're currently doing for user docs.

jotes · 2021-03-18T16:20:05Z

specs/0104-documentation-overhaul.md

+
+Documentation is stored in the `docs` folder within the Pontoon code repository.
+
+Having documentation in the same place as the code base allows us to enforce documentation updates along with code updates.


I see a problem there related to the fact that every link is going to point to the latest version? e.g. when a translator discusses a document that changes over time and there's no way to reference the previous version.

srl295 · 2024-01-25T18:28:47Z

Should the buglink be #2214 ?

mathjazz · 2024-03-12T18:24:53Z

This patch has been stalled for a while.

Let's reopen when work continues.

adngdb added the spec Specification proposal label Feb 20, 2020

gueroJeff reviewed Feb 26, 2020

View reviewed changes

mathjazz force-pushed the 1616869-documentation-overhaul-spec branch from e12d4c1 to bfa358d Compare July 14, 2020 13:53

adngdb and others added 5 commits March 17, 2021 02:34

Bug 1616869 - Write a specification for the documentation overhaul.

e8aa672

Update roles, merging Contributor and Core developer, and clarifying …

dc75bf0

…names.

Add a note about moderation in wiki.

e8f8dbb

Update spec number: Latest spec (even if not merged yet) +1

04c4ca5

Convert RFC to a Spec

8c14c34

mathjazz force-pushed the 1616869-documentation-overhaul-spec branch from d35ecf7 to 8c14c34 Compare March 17, 2021 01:34

mathjazz reviewed Mar 17, 2021

View reviewed changes

Pike reviewed Mar 17, 2021

View reviewed changes

flodolo reviewed Mar 18, 2021

View reviewed changes

jotes reviewed Mar 18, 2021

View reviewed changes

mathjazz mentioned this pull request May 23, 2022

Mention the existence of Django admin in docs #2535

Open

mathjazz mentioned this pull request Jan 25, 2024

Add a way to request a new locale directly through Pontoon #2135

Open

mathjazz closed this Mar 12, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] Bug 1616869 - Documentation overhaul specification #1570

[RFC] Bug 1616869 - Documentation overhaul specification #1570

adngdb commented Feb 20, 2020

flodolo commented Feb 20, 2020

mathjazz commented Feb 21, 2020 •

edited

mathjazz commented Feb 21, 2020

adngdb commented Feb 25, 2020

adngdb commented Feb 25, 2020

mathjazz commented Feb 26, 2020

gueroJeff Feb 26, 2020

gueroJeff Feb 26, 2020

adngdb Mar 3, 2020

gueroJeff Feb 26, 2020

gueroJeff Feb 26, 2020

Pike commented May 6, 2020

adngdb commented May 10, 2020

Pike commented Jul 1, 2020

mathjazz commented Aug 12, 2020 •

edited

mathjazz Mar 17, 2021

jotes Mar 18, 2021

Pike Mar 17, 2021

Pike Mar 17, 2021

jotes Mar 18, 2021

Pike Mar 17, 2021

Pike Mar 17, 2021

mathjazz Mar 17, 2021

flodolo left a comment

jotes Mar 18, 2021

srl295 commented Jan 25, 2024

mathjazz commented Mar 12, 2024


		Cons

		- Contributing to the documentation is difficult as it requires making a pull request on GitHub.


		## Where to host

		Documentation is hosted in a dedicated section within Pontoon app (`/docs`) and built on each deployment.


		## What format to use

		Documentation is writen using the Markdown syntax.


		Documentation is stored in the `docs` folder within the Pontoon code repository.

		Having documentation in the same place as the code base allows us to enforce documentation updates along with code updates.


		## Maintenance

		TBD

[RFC] Bug 1616869 - Documentation overhaul specification #1570

[RFC] Bug 1616869 - Documentation overhaul specification #1570

Conversation

adngdb commented Feb 20, 2020

flodolo commented Feb 20, 2020

mathjazz commented Feb 21, 2020 • edited

mathjazz commented Feb 21, 2020

adngdb commented Feb 25, 2020

adngdb commented Feb 25, 2020

mathjazz commented Feb 26, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Pike commented May 6, 2020

adngdb commented May 10, 2020

Pike commented Jul 1, 2020

mathjazz commented Aug 12, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flodolo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srl295 commented Jan 25, 2024

mathjazz commented Mar 12, 2024

mathjazz commented Feb 21, 2020 •

edited

mathjazz commented Aug 12, 2020 •

edited