938364 - Create a non-HTML repo for creating Marketplace legal documents

Status: RESOLVED FIXED

(Marketplace Graveyard :: General, defect)

Description

[Matt Basta [:basta]]

cvan shouldn't be spending his time converting Word documents to HTML. Proposal:

- Create a Github repo (marketplace-docs) that mimics the structure of Zamboni's /media/docs directory
- Each legal document will be produced in Markdown format in the corresponding directory's en-US.md file
- Localizers will copy the en-US.md document to the locale that they work on (e.g.: es-ES.md, pt-BR.md) and localize that
- A small shell script will be written (to be used by Marketplace devs) to convert the Markdown to HTML
- If a path is given, the script could even copy the HTML to Zamboni and create a commit

Current workflow:
- Legal produces documents in Word
- Legal sends Word files to someone
- Someone sends the files to cvan
- cvan labouriously converts each document by hand to HTML
- cvan takes a short break because he has delicate fingers and that's a lot of typing
- cvan finishes converting each document by hand to HTML
- cvan closes a bunch of bugs
- Everybody mourns the loss of cvan's time

Proposed workflow:
- Legal produces documents in Markdown via the Github Edit button
- Someone files a bug
- cvan runs `git pull && ./magic_markdown.ss`
- cvan closes a single bug
- cvan makes some tea

Legal would have the option of using the Github edit button or using a local client (the OS X client, or the Windows client).

If need be, we could just as easily give them access to Potch's fine Markdown editor.

Pros:
- Many thousands of dollars worth of time is saved
- cvan can work on other things
- Our lawyers can add a new skill to their resumes
- We don't need to keep purchasing Office licenses
- All of the work that Legal does will be version controlled and centrally available
- Fewer human errors in the manual conversion of Word->HTML

Cons:
- It might take Legal an hour or so to read the Markdown guide
- The jimmies of many will be rustled since there will be a new workflow
- We might need to use a private repo
- Someone will need to explain how this works to the legal team (we could get Chuck to make another screencast!)

Comment 1

[Matt Basta [:basta]]

I've gotten all of the english versions ported to Markdown and all of the privacy policy translations ported to Markdown as well:

https://github.com/mozilla/marketplace-docs/tree/master/docs

The only thing remaining is the translations of the developer agreement and the terms of use, as well as creating a script and educating the legal team.

Note that I left in the HTML entities for curly quotes and the like...we may want to replace those with straight quotes and/or UTF-8 characters for simplicity. Github Markdown will not convert curly quotes to HTML entities, so bear that in mind.

Comment 2

[Matt Basta [:basta]]

I've finished porting our docs over, and have talked with dbialer to get a meeting set up with legal.

Comment 3

[Matt Basta [:basta]]

Spoken to legal, they like it and will try to start using it.