From 8cece6ace6a2257d27ef01f23e1036e8de8e5a75 Mon Sep 17 00:00:00 2001 From: fscelliott <42477011+fscelliott@users.noreply.github.com> Date: Tue, 22 Sep 2020 10:24:19 -0600 Subject: [PATCH] small updates to readme for docs authoring --- ...DOCS_HERE.md => 001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md} | 2 +- docs/readme.md | 9 +++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) rename docs/readme-sync/deploy-as-a-microservice/{001 - DONT_AUTHOR_AGENT_DOCS_HERE.md => 001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md} (68%) diff --git a/docs/readme-sync/deploy-as-a-microservice/001 - DONT_AUTHOR_AGENT_DOCS_HERE.md b/docs/readme-sync/deploy-as-a-microservice/001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md similarity index 68% rename from docs/readme-sync/deploy-as-a-microservice/001 - DONT_AUTHOR_AGENT_DOCS_HERE.md rename to docs/readme-sync/deploy-as-a-microservice/001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md index 371fd9ca..a17a19d0 100644 --- a/docs/readme-sync/deploy-as-a-microservice/001 - DONT_AUTHOR_AGENT_DOCS_HERE.md +++ b/docs/readme-sync/deploy-as-a-microservice/001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md @@ -7,4 +7,4 @@ createdAt: "2020-02-21T17:44:53.019Z" updatedAt: "2020-04-13T23:02:34.056Z" --- -Agent docs sync from Github. So, any changes you author here in Readme will just be overwritten. Make docs updates over in Github. For more info, see [authoring guidelines in githuyb](https://github.com/optimizely/agent/blob/master/docs/internal%20docs%20authoring%20notes.md). +Agent docs sync from Github. So, any changes you author here in Readme will just be overwritten. Make docs updates over in Github. For more info, see [authoring guidelines in github](https://github.com/optimizely/agent/blob/master/docs/internal%20docs%20authoring%20notes.md). diff --git a/docs/readme.md b/docs/readme.md index 1faa9ab0..04155680 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -4,6 +4,10 @@ When you edit the docs in /docs/readme-sync/ and merge to the master branch, you trigger a Travis build stage (readme-sync) that syncs the Markdown doc files to FullStack public docs at https://docs.developers.optimizely.com/full-stack/docs/optimizely-agent. +### Previewing + +Before you commit to master, there's a travis stage that syncs your branch's changes to a ReadMe sandbox so you can preview the published output, https://docs.developers.optimizely.com/full-stack/docs/ (you need to be logged into ReadMe to see this sandbox, since it's not public). + ### Directory and filename requirements See https://github.com/flowcommerce/readme-sync. @@ -17,7 +21,7 @@ You can author the docs in Github-flavored Markdown, with the following minor re - **links** - You can use relative links, but you have to leave out the .md extension. Like this: [relative link to a doc](./readme-sync/deploy-as-a-microservice). (Future improvement: should be easy to modify readme-sync code to strip out .md extensions if we want working relative links in the markdown stored in github) - **images** - You can't use relative links. Currently, we use hyperlinks to images stored on the master branch [like this](). - **manual edits to updatedAt:** the frontmatter in each markdown page includes an updatedAt field, which you must manually edit when you commit a page, so that the public docs display the correct info at the bottom of the page ("Updated x days ago"). -- **no semantic code snippets / language highlighting** ReadMe gets confused if you use a code block snippet that indicates the language. It erratically interprets #code comments as heading markdown syntax. So avoid: +- **no semantic code snippets / language highlighting** ReadMe gets confused if you use a code block snippet that indicates the language. It erratically interprets #code comments as heading markdown syntax. So if you have a bunch of headings, then avoid: ```python # some python code here @@ -35,7 +39,8 @@ and only use: ### Future improvements -- **preview pages** - we don't have a mechanism to preview the markdown on ReadMe.io before merging to master, so you may want to 'raw copy' your markdown into a hidden ReadMe page to preview your content. (an easy way to achieve previews would be to write a Travis stage that syncs to a private ReadMe sandbox on commits to pull requests.) + + - **build conflict resolution** - If 2 Travis builds tried to sync to readme at the same time, one could overwrite the other. Build duration is ~5 minutes. (One way to get to eventual consistency might be to run a nightly Travis build that syncs to Readme.) - **no automatic updates to readme-sync** - The engine for this sync is an externally developed tool that uses the ReadMe API called readme-sync. We clone readme-sync not from the public repo, but from a mirrored repo (https://travis-ci.com/github/optimizely/readme-sync2) that was set up in early 2020. So over time we'll miss out on updates to readme-sync https://github.com/flowcommerce/readme-sync.