Scott and I used Microsoft Word for our Hands On Lab at Oracle Code One. This worked “mostly” fine. The quotes are because we had a one merge conflict when writing the instructions.
At the conference, an attendee (Barry Evans) said he had some improvements to the docs and he’d submit a pull request. Less than useful in Word so I asked him to email me with change tracking. i thought better of that and decided to convert to Markdown.
It wasn’t as bad as I thought:
- First, I used the Word to Markdown converter to do a first level pass
- Then I manually split it into a page per step (cut/paste) and changed the table of contents to links.
- Next, I converted the images to local ones in the repo.
- Finally, I did cleanup on code that didn’t format right, lists that were broken and using better code tags.
I used Visual Studio Code as the markdown editor. (I’ve been trying to get more comfortable with VS Code). I learned:
- Having the markdown file in the left pane and a split view with the preview is nice. They even stay in sync with content/paging.
- Command up/down goes to the top/bottom of the doc.
- Home/End goes to the beginning/end of a line.
- You can test markdown links directly in the preview editor.
- The preview editor shows images so I could easily spot typos.
I tagged the repo version with the Word doc in case I ever want to go back to what it looked like.