diff --git a/docs/documentation/documentation.md b/docs/documentation/documentation.md new file mode 100644 index 000000000..085639154 --- /dev/null +++ b/docs/documentation/documentation.md @@ -0,0 +1,126 @@ +# How to Contribute to the Documentation + +This documenation is currently hosted live at [Spiff-Arena's ReadTheDocs](https://spiff-arena.readthedocs.io/en/latest/) + + +Please set aside a couple of hours to work through this, as getting this setup correctly once is 10,000 times better than having problems every day for the rest of your life. + +## Our Methodology + +The methodology we are following is knowns as ["Docs as Code"](https://www.writethedocs.org/guide/docs-as-code/) + +This means using the same tools and processes that software developers use for writing code to write the documenation for code. +In following this methodoloy, you will have to pick up some tools you haven't had to use before (Git, Sphinx). +Why would a technical writer need to learn these software engineering tools? +I'll never make the case for as well as an article by [Tom Johnson](https://idratherbewriting.com/trends/trends-to-follow-or-forget-docs-as-code.html). + +You might notice, when looking at the markdown files, that every sentence starts on a new line. +Like this one. +Unless there is a blank line between sentences, Markdown will still render this as a paragraph. +This is called [Ventilated Code](https://vanemden.wordpress.com/2009/01/01/ventilated-prose/) and can be very helpful when working in Markdown. + + +## Our Tools + +[Markdown](https://www.markdownguide.org/getting-started/) is a "markup language that you can use to add formatting elements to plain text documents. +You won't be writing the documentation in a word processor, but in simple plain text, and using some special syntax that will consistently and professionally format that text. + + +The basic Markdown syntax is very simple. Here are some [quick examples](https://commonmark.org/help/). And here is a great [10 minute tutorial](https://commonmark.org/help/tutorial/). +This will cover a lot of the basics, like bolding text, italics, paragraphs, lists and other common formatting techniques. + +![Markdown screenshot](./images/markdown.png "Markdown example") + +### MyST +Markdown doesn't support some really useful things. +You can't add footnotes, or create an "aside" comment or build a table. +Because of this there are many extensions typically referened to as Markdown "Flavors". +The flavor we are using is MyST. +There is [excellent documentation on MyST](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax.html) that you should definitely review, so you know everthing that is available to you. + + +### Sphinx +This is a large documenation effort. Many different Markdown pages will together make up the full website. + +You will mostly use Sphinx in the background - you won't be aware of it. +But if you decide that you want to alter the theme (the colors, styles, etc...) of the final website, Sphinx controls this and offers [themes](https://sphinx-themes.org/) and the ability to change styles / colors and formatting through the site. +You just need to learn a little CSS to control it. + + +### GitHub +Our project is managed by a version control system called Git. +You can use GIT to submit changes to the documenation, in the same we use to submit changes to our code. +It is avilable on GitHub as the [spiff-arena project](https://github.com/sartography/spiff-arena). Git also manages versions of the code, and handles running tests, and causing our documenation to be built and deployed. +It will take a bit to get comfortable with Git, but when you do, you will come to love it (or maybe hate it, but with a lot of respect) + +## Setup + +So that's a lot of tools, and seemingly a lot to learn. +But you will find that most of it just works - and that once you get into a regular flow, it will become second nature. + + +### Step 1: Pre-Requisites +Assure you have been granted write access to our repository. +Make sure you have an account on GitHub and then contact dan@sartography.com and ask him to add you as a contributor. + + +### Step 2: Install VSCode +[Download VSCode](https://code.visualstudio.com/) and install it on your computer. + +### Step 3: Install Python +We need python in order to build the website locally so we can really see what our content is going to look like once we publish. It's going to be handy for other reasons as well. We'll want python to be properly set up inside of VS Code. Follow [these directions and brief tutorial](https://code.visualstudio.com/docs/python/python-tutorial +) to assure this is set up. + + + +### Step 3: Connect VSCode to Git +VSCode comes with Git built in. +So you can use VSCode to "pull" changes from others down to your local computer and "push" changes back up to share with others (and to cause our docs site to rebuild) + +Here are directions for how to [clone Spiff-Arena](https://learn.microsoft.com/en-us/azure/developer/javascript/how-to/with-visual-studio-code/clone-github-repository?tabs=create-repo-command-palette%2Cinitialize-repo-activity-bar%2Ccreate-branch-command-palette%2Ccommit-changes-command-palette%2Cpush-command-palette#clone-repository). **IMPORTANT**: Follow those directions, but be sure to checkout https://github.com/sartography/spiff-arena instead of the project they are using! + +You can save the project to any directory on your computer. +We strongly suggest you create a sub-folder called "projects" in your "home" or "Desktop" folder and checkout the code into this directory. + +### Step 4: Open just the Docs Folder + +We've checked out the whole spiff-arena project, but we are only going to be working inside of the docs directory. So let's open just that folder in VSCode. + +* Go to File -> Open Folder +* Select the "docs" folder inside of spiff-arena. + +Now clikc on the two pieces of paper at the top corner of your screen, and you should see a project that looks like this: + +![Docs Directory](./images/docs_dir.png "Docs Directory") + +Without all the rest of the code in your way. + +### Step 4: Add some extensions + * Inside VSCode, go to File -> Preferences -> Extensions + * Search for "myst" + * click the "install" button. + * Repeat, this time doing it for "python extension for VS Code" + +![Myst Extension](./images/myst.png "Search or MyST in extensions") + + +### Step 5: Install Python Dependencies +This project requires a few Python dependencies to work correctly. We are going to set up a Virtual Evironment for Python to keep us sane later on. You can do that by following these steps: + +1. Open the Command Palette (Ctrl+Shift+P), start typing the **Python: Create Environment** command to search, and then select the command. +1. Select **Venv** +1. Select Python 3.11 from the list of options if there is nore than one thing to select. +1. Be sure the the checkbox next to "requirements.txt" is selected. +1. Click OK. + +### Step 6: Fire up the website +1. Go to Terminial -> New Terminal +1. type: **sphinx-autobuild . _build/html** at the prompt and hit enter. +1. Open your browser and go to http://127.0.0.1:8000 + + +### Step 7: Make a chance +1. Open up a markdown file, and make a change. + +### Step 8: Commit your changes and push them up for everyone. +1. diff --git a/docs/documentation/images/commit.webp b/docs/documentation/images/commit.webp new file mode 100644 index 000000000..203437683 Binary files /dev/null and b/docs/documentation/images/commit.webp differ diff --git a/docs/documentation/images/docs_dir.png b/docs/documentation/images/docs_dir.png new file mode 100644 index 000000000..c2e36fa17 Binary files /dev/null and b/docs/documentation/images/docs_dir.png differ diff --git a/docs/documentation/images/markdown.png b/docs/documentation/images/markdown.png new file mode 100644 index 000000000..91c13e037 Binary files /dev/null and b/docs/documentation/images/markdown.png differ diff --git a/docs/documentation/images/myst.png b/docs/documentation/images/myst.png new file mode 100644 index 000000000..919ad53f7 Binary files /dev/null and b/docs/documentation/images/myst.png differ diff --git a/docs/quick_start/images/Untitled.png b/docs/quick_start/images/Untitled.png new file mode 100644 index 000000000..95c7a4ff3 Binary files /dev/null and b/docs/quick_start/images/Untitled.png differ diff --git a/docs/quick_start/images/Untitled_1.png b/docs/quick_start/images/Untitled_1.png new file mode 100644 index 000000000..8289df4b5 Binary files /dev/null and b/docs/quick_start/images/Untitled_1.png differ diff --git a/docs/quick_start/images/Untitled_10.png b/docs/quick_start/images/Untitled_10.png new file mode 100644 index 000000000..20aae62c6 Binary files /dev/null and b/docs/quick_start/images/Untitled_10.png differ diff --git a/docs/quick_start/images/Untitled_11.png b/docs/quick_start/images/Untitled_11.png new file mode 100644 index 000000000..4d7167c17 Binary files /dev/null and b/docs/quick_start/images/Untitled_11.png differ diff --git a/docs/quick_start/images/Untitled_12.png b/docs/quick_start/images/Untitled_12.png new file mode 100644 index 000000000..429372666 Binary files /dev/null and b/docs/quick_start/images/Untitled_12.png differ diff --git a/docs/quick_start/images/Untitled_13.png b/docs/quick_start/images/Untitled_13.png new file mode 100644 index 000000000..b0c07d7e8 Binary files /dev/null and b/docs/quick_start/images/Untitled_13.png differ diff --git a/docs/quick_start/images/Untitled_14.png b/docs/quick_start/images/Untitled_14.png new file mode 100644 index 000000000..4d7167c17 Binary files /dev/null and b/docs/quick_start/images/Untitled_14.png differ diff --git a/docs/quick_start/images/Untitled_15.png b/docs/quick_start/images/Untitled_15.png new file mode 100644 index 000000000..08f77d6a1 Binary files /dev/null and b/docs/quick_start/images/Untitled_15.png differ diff --git a/docs/quick_start/images/Untitled_16.png b/docs/quick_start/images/Untitled_16.png new file mode 100644 index 000000000..24063a122 Binary files /dev/null and b/docs/quick_start/images/Untitled_16.png differ diff --git a/docs/quick_start/images/Untitled_17.png b/docs/quick_start/images/Untitled_17.png new file mode 100644 index 000000000..5f87b7475 Binary files /dev/null and b/docs/quick_start/images/Untitled_17.png differ diff --git a/docs/quick_start/images/Untitled_18.png b/docs/quick_start/images/Untitled_18.png new file mode 100644 index 000000000..eec05dc8f Binary files /dev/null and b/docs/quick_start/images/Untitled_18.png differ diff --git a/docs/quick_start/images/Untitled_19.png b/docs/quick_start/images/Untitled_19.png new file mode 100644 index 000000000..c79620c88 Binary files /dev/null and b/docs/quick_start/images/Untitled_19.png differ diff --git a/docs/quick_start/images/Untitled_2.png b/docs/quick_start/images/Untitled_2.png new file mode 100644 index 000000000..fb3ba47dd Binary files /dev/null and b/docs/quick_start/images/Untitled_2.png differ diff --git a/docs/quick_start/images/Untitled_20.png b/docs/quick_start/images/Untitled_20.png new file mode 100644 index 000000000..8b893f7bb Binary files /dev/null and b/docs/quick_start/images/Untitled_20.png differ diff --git a/docs/quick_start/images/Untitled_21.png b/docs/quick_start/images/Untitled_21.png new file mode 100644 index 000000000..653765ff6 Binary files /dev/null and b/docs/quick_start/images/Untitled_21.png differ diff --git a/docs/quick_start/images/Untitled_22.png b/docs/quick_start/images/Untitled_22.png new file mode 100644 index 000000000..8a0c335c6 Binary files /dev/null and b/docs/quick_start/images/Untitled_22.png differ diff --git a/docs/quick_start/images/Untitled_23.png b/docs/quick_start/images/Untitled_23.png new file mode 100644 index 000000000..1d650d5bc Binary files /dev/null and b/docs/quick_start/images/Untitled_23.png differ diff --git a/docs/quick_start/images/Untitled_24.png b/docs/quick_start/images/Untitled_24.png new file mode 100644 index 000000000..039e31c40 Binary files /dev/null and b/docs/quick_start/images/Untitled_24.png differ diff --git a/docs/quick_start/images/Untitled_25.png b/docs/quick_start/images/Untitled_25.png new file mode 100644 index 000000000..f912d4ccd Binary files /dev/null and b/docs/quick_start/images/Untitled_25.png differ diff --git a/docs/quick_start/images/Untitled_26.png b/docs/quick_start/images/Untitled_26.png new file mode 100644 index 000000000..e45f20b42 Binary files /dev/null and b/docs/quick_start/images/Untitled_26.png differ diff --git a/docs/quick_start/images/Untitled_27.png b/docs/quick_start/images/Untitled_27.png new file mode 100644 index 000000000..e81db9795 Binary files /dev/null and b/docs/quick_start/images/Untitled_27.png differ diff --git a/docs/quick_start/images/Untitled_28.png b/docs/quick_start/images/Untitled_28.png new file mode 100644 index 000000000..93776de4a Binary files /dev/null and b/docs/quick_start/images/Untitled_28.png differ diff --git a/docs/quick_start/images/Untitled_29.png b/docs/quick_start/images/Untitled_29.png new file mode 100644 index 000000000..2f646c01c Binary files /dev/null and b/docs/quick_start/images/Untitled_29.png differ diff --git a/docs/quick_start/images/Untitled_3.png b/docs/quick_start/images/Untitled_3.png new file mode 100644 index 000000000..98aecc31e Binary files /dev/null and b/docs/quick_start/images/Untitled_3.png differ diff --git a/docs/quick_start/images/Untitled_30.png b/docs/quick_start/images/Untitled_30.png new file mode 100644 index 000000000..0cdb7474f Binary files /dev/null and b/docs/quick_start/images/Untitled_30.png differ diff --git a/docs/quick_start/images/Untitled_31.png b/docs/quick_start/images/Untitled_31.png new file mode 100644 index 000000000..b059a4adb Binary files /dev/null and b/docs/quick_start/images/Untitled_31.png differ diff --git a/docs/quick_start/images/Untitled_32.png b/docs/quick_start/images/Untitled_32.png new file mode 100644 index 000000000..2e99f7c0a Binary files /dev/null and b/docs/quick_start/images/Untitled_32.png differ diff --git a/docs/quick_start/images/Untitled_4.png b/docs/quick_start/images/Untitled_4.png new file mode 100644 index 000000000..6d827afa8 Binary files /dev/null and b/docs/quick_start/images/Untitled_4.png differ diff --git a/docs/quick_start/images/Untitled_5.png b/docs/quick_start/images/Untitled_5.png new file mode 100644 index 000000000..e06a5afa3 Binary files /dev/null and b/docs/quick_start/images/Untitled_5.png differ diff --git a/docs/quick_start/images/Untitled_6.png b/docs/quick_start/images/Untitled_6.png new file mode 100644 index 000000000..767e30c74 Binary files /dev/null and b/docs/quick_start/images/Untitled_6.png differ diff --git a/docs/quick_start/images/Untitled_7.png b/docs/quick_start/images/Untitled_7.png new file mode 100644 index 000000000..f7c600bf6 Binary files /dev/null and b/docs/quick_start/images/Untitled_7.png differ diff --git a/docs/quick_start/images/Untitled_8.png b/docs/quick_start/images/Untitled_8.png new file mode 100644 index 000000000..7ac61b793 Binary files /dev/null and b/docs/quick_start/images/Untitled_8.png differ diff --git a/docs/quick_start/images/Untitled_9.png b/docs/quick_start/images/Untitled_9.png new file mode 100644 index 000000000..325794d6d Binary files /dev/null and b/docs/quick_start/images/Untitled_9.png differ