Skip to content

small updates to readme for docs authoring #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 22, 2020
Merged

small updates to readme for docs authoring #280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...vice/001 - DONT_AUTHOR_AGENT_DOCS_HERE.md → ...vice/001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
9 changes: 7 additions & 2 deletions docs/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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.

Expand Down