Markdown repository for PR texts

[xaur]

Overview of existing formats and workflows for PR-related texts:

PDF (previously used in business brief) is hard to edit and hard to collaborate, people used to exchange edited/annotated PDF files back and forth in chat, there's no history or version diffs.

HTML (current format in dcrweb) is hard to edit for writers who are only interested in text and no ugly HTML markup, the markup complicates diffing and review

pastebin is better but pastes are not linked together in a historic chain, and the ones posted so far were not markdown (=> don't preserve formatting and links). Perhaps the strong feature of pastebin is you can use it without account.

gist is better than pastebin (adds history and people can comment on gists). gist is perfect for single document where you don't expect collaboration.

Google Docs has very strong collaboration UX and allows very fast iteration by multiple people. It's good for initial brainstorming and bootstrapping the document. The price is you have no access to underlying format and it is closed. On the surface this sounds like a geek complaint, but it leads multiple restrictions. No access to native format means you can only get "exported" versions out (.doc, odt, .txt) which all lose some features. Put simply, vendor lock. Also you can't "export" the history in any meaningful format. There are also obvious privacy concerns of executing a ton of obfuscated code from Google.

There are advantages to having all PR texts in a) Markdown format in b) single Git repo hosted on GitHub.

• Git+Markdown is perfect from the data and freedom perspective.
• PR stuff will grow to many documents that are nice to have in one place. In PR every single word matters. When you change messaging you need to change all places. When all PR texts are in one master repo you easily find all occurrences with standard text tools
• can benefit from collaboration tools of GitHub not found in PDF, pastebin and gist.
• can seamlessly "plug in" developers who all have GitHub accounts, they can participate in reviews and comment on individual changes.

Git+Markdown has problems with UX. It's mostly ok if you stick to GitHub's web editor and have someone to maintain the repo. I imagine a hybrid workflow where people collaboratively do many small iterations in Google Docs and periodically save major versions in Git.

What can kinds of documents?

• business brief
• messaging platform
• texts used at events for handouts (business cards, folds, posters, booth, etc)
• various pitches and taglines from the community (can also live in a sibling wiki, with selected stuff flowing into the repo)

Initially discussed in this chat.

cc @Dustorf

[xaur]

Found one downside: public GitHub repo is "more public" than Google Doc (assuming "only people with the link can view" mode) and than our chats. This can be addressed by using Bitbucket or GitLab which allows private repos (I'd vote for GitLab, we may need it anyway).

Not sure to what extent this is an issue, need more opinions.

[xaur]

So we have this repository with PR guidance from Ditto:

https://github.com/decredcommunity/pr

Looking good so far - I have all PR docs in one place and mirrored locally.

Been wondering about organizing data. The current contents of the pr repo are essentially guidelines (i.e. no brief or handouts atm) for the PR (Outreach) domain. There is another guidelines repo that collects jz's docs (how to act on conferences, how to tweet, etc), Reddit mod tips and the work-in-progress general mod policy.

Since both are "guidelines" type, I wondered if they should be merged into a single repo where "pr" is just a directory? There are two ways to group:

1. group all guidelines for all domains in one repo
2. group per domain, in this case the pr repo can have both guidelines and other PR documents (such as handout texts)

I'm leaning to the latter. This is no big deal, we can always merge repos while splitting them keeping history is difficult.