From d3e52ceedc0e069552898422adce50f04f6d886d Mon Sep 17 00:00:00 2001 From: Frances Elliott <42477011+fscelliott@users.noreply.github.com> Date: Mon, 20 Jul 2020 09:38:41 -0600 Subject: [PATCH 1/3] Create internal docs authoring notes.md --- docs/internal docs authoring notes.md | 51 +++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/internal docs authoring notes.md diff --git a/docs/internal docs authoring notes.md b/docs/internal docs authoring notes.md new file mode 100644 index 00000000..ca719b27 --- /dev/null +++ b/docs/internal docs authoring notes.md @@ -0,0 +1,51 @@ +## Internal docs authoring notes + + + +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. + +### Directory and filename requirements + +See https://github.com/flowcommerce/readme-sync. + + + +### Authoring requirements & limitations + +You can author the docs in Github-flavored Markdown, with the following minor restrictions and caveats: + +- **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: + +```python +# some python code here +``` + +and only use: + +``` +# some code in some unspecified language here +``` + +- **authoring guardrails ReadMe.io** - If someone doesn't know better, they could edit the Agent docs in dash.readme... but those edits will be overwritten the next time triggers the readme-sync Travis stage. There's no mechanism in dash.readme to warn them not to edit. Likewise, any suggested edits in ReadMe need to be manually merged to the Github docs rather than merged using ReadMe's mechanism. + + + +### 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. + + + + + +### + + + + + From ac234ccf089762aa2e9802a52ce53d65fb51505d Mon Sep 17 00:00:00 2001 From: Frances Elliott <42477011+fscelliott@users.noreply.github.com> Date: Mon, 20 Jul 2020 09:40:50 -0600 Subject: [PATCH 2/3] Update internal docs authoring notes.md --- docs/internal docs authoring notes.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/internal docs authoring notes.md b/docs/internal docs authoring notes.md index ca719b27..1faa9ab0 100644 --- a/docs/internal docs authoring notes.md +++ b/docs/internal docs authoring notes.md @@ -29,7 +29,7 @@ and only use: # some code in some unspecified language here ``` -- **authoring guardrails ReadMe.io** - If someone doesn't know better, they could edit the Agent docs in dash.readme... but those edits will be overwritten the next time triggers the readme-sync Travis stage. There's no mechanism in dash.readme to warn them not to edit. Likewise, any suggested edits in ReadMe need to be manually merged to the Github docs rather than merged using ReadMe's mechanism. +- **no authoring in dash.readme** - If someone doesn't know better, they could edit the Agent docs in dash.readme... but those edits will be overwritten the next time triggers the readme-sync Travis stage. There's no mechanism in dash.readme to warn them not to edit. Likewise, any suggested edits in ReadMe need to be manually merged to the Github docs rather than merged using ReadMe's mechanism. @@ -43,8 +43,6 @@ and only use: -### - From 1c3374f7ec780e31249f28881be7e187a4318ce7 Mon Sep 17 00:00:00 2001 From: Frances Elliott <42477011+fscelliott@users.noreply.github.com> Date: Mon, 20 Jul 2020 14:59:39 -0600 Subject: [PATCH 3/3] adding code comment --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index f2592c5c..6c8fa58b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -247,6 +247,7 @@ jobs: ######################################################################################### # directories/scripts for full SDK-reference-guides, to be implemented after agent docs sync ######################################################################################### + # this commented out code can be used to implement: https://optimizely.atlassian.net/browse/OASIS-6807 ## this preps the input directory for readme-sync script #- mkdir -p $HOME/readme-sync2/docs/readme-sync/sdk-reference-guides ## ${TRAVIS_REPO_SLUG#optimizely/} translates to go-sdk docs/readme-sync/sdk-reference-guides/go-sdk