documentation reorganization and page standardization #858

conceptualshark · 2022-07-11T20:53:42Z

Purpose

The fidesops documentation had no or alternating standards that varied from page to page. This sweep brings every page in alignment for formatting, styling, and copy. The contents walkthrough is also updated to represent a more streamlined/understandable experience, separating out multiple sections.

This fix does not include rewriting any guides, which will ensure all documents flow from one to the next, and will come in a later update.

Changes

update uses of Fidesops to fidesops to conform to documentation and style standards
all titles and headings now sentence case
standardize titles of all code blocks when using filenames and http methods
standardize formatting of guides and walkthroughs
reorganize the information flow/architecture
general copy edits

Checklist

Update CHANGELOG.md file
- Merge in main so the most recent CHANGELOG.md file is being appended to
- Add description within the Unreleased section in an appropriate category. Add a new category from the list at the top of the file if the needed one isn't already there.
- Add a link to this PR at the end of the description with the PR number as the text. example: #1
Applicable documentation updated (guides, quickstart, postman collections, tutorial, fidesdemo, database diagram.
If docs updated (select one):
- documentation complete, or draft/outline provided (tag docs-team to complete/review on this branch)

Ticket

Fixes #427, DOX-216

…[DOX-216]

seanpreston · 2022-07-12T10:17:44Z

docs/fidesops/docs/development/documentation.md

@@ -14,7 +12,7 @@ To write concept docs, add Markdown files to the `docs/fidesops/docs/` directory

 ### Capitalization

-Concepts that refer to proper nouns or are trademarked should always be capitalized, including "Fides" and "Fidesops".
+Concepts that refer to proper nouns or are trademarked should always be capitalized, including "Fides".


This could be misleading — should we explicitly state not to capitalise fidesops? We ought to mention the sentence case requirement for headings too.

I want to do a more comprehensive rewrite of this to encompass the new tone/style changes we're still finishing up - I added the note about using lowercase for Fides tools, but will include more docs on headers/titles when the guide is finished up.

pattisdr

Nice improvements @conceptualshark!

pattisdr · 2022-07-12T15:56:23Z

CHANGELOG.md

@@ -27,30 +27,29 @@ The types of changes are:
 * Adds endpoint to get the secrets required for different connectors [#795](https://github.com/ethyca/fidesops/pull/795)
 * Store provided identity data in the privacy request table [#743](https://github.com/ethyca/fidesops/pull/834)

+## Changed


Looks like Changed should have three pound signs.

pattisdr · 2022-07-12T15:58:23Z

README.md

 how to handle user data, and execute access and erasure requests.  But there's a lot more to discover,
 so we'd recommend following [the tutorial](https://ethyca.github.io/fidesops/tutorial/) to keep learning.

 ### Documentation

-For more information on getting started with Fidesops, how to configure and set up Fidesops, and more about the Fides ecosystem of open source projects: 
+For more information on getting started with fidesops, how to configure and set up fidesops, and more about the Fides ecosystem of open source projects: 


Below, under License: do those need to be lowercased?

The Fides ecosystem of tools (Fidesops and Fidesctl) are licensed under the ...

pattisdr · 2022-07-12T16:01:01Z

docs/fidesops/docs/development/jetbrains_debugging.md

-# Debugging Fidesops in IntelliJ IDEA Ultimate
-This guide will show how to use the IntelliJ debugger with Fidesops running in Docker. 
+# Debugging fidesops in IntelliJ IDEA Ultimate
+This guide will show how to use the IntelliJ debugger with fidesops running in Docker. 
 The setup for PyCharm Professional should be very similar.

 ## Prerequisites


Should the Fidesops prerequisite be lowercased?

pattisdr · 2022-07-12T16:02:29Z

docs/fidesops/docs/development/overview.md

@@ -89,4 +89,4 @@ In order to submit code to Fidesops, please:



L87 - Once approved, your PR will be merged into Fidesops.

Lowercase?

pattisdr · 2022-07-12T16:05:01Z

docs/fidesops/docs/guides/configuration_reference.md

-| `LOG_LEVEL` | `FIDESOPS__SECURITY__LOG_LEVEL` | string | INFO | N/A | The log level used for Fidesops. Must be one of DEBUG, INFO, WARNING, ERROR, or CRITICAL |
+| `APP_ENCRYPTION_KEY` | `FIDESOPS__SECURITY__APP_ENCRYPTION_KEY` | string | OLMkv91j8DHiDAULnK5Lxx3kSCov30b3 | N/A | The key used to sign fidesops API access tokens |
+| `CORS_ORIGINS` | `FIDESOPS__SECURITY__CORS_ORIGINS` | List[AnyHttpUrl] | ["https://a-client.com/", "https://another-client.com"/] | N/A | A list of pre-approved addresses of clients allowed to communicate with the fidesops application server |
+| `LOG_LEVEL` | `FIDESOPS__SECURITY__LOG_LEVEL` | string | INFO | N/A | The log level used for fidesops. Must be one of DEBUG, INFO, WARNING, ERROR, or CRITICAL |
 | `OAUTH_ROOT_CLIENT_ID` | `FIDESOPS__SECURITY__OAUTH_ROOT_CLIENT_ID` | string | fidesopsadmin | N/A | The value used to identify the Fidesops application root API client |


The value used to identify the Fidesops application root API client

Lowercase?

pattisdr · 2022-07-12T16:44:53Z

docs/fidesops/docs/guides/query_execution.md

@@ -2,9 +2,9 @@

 ## Graphs and Traversals

-Fidesops uses your Datasets to generate a _graph_ of the resources. Based on the identity data you provide, Fidesops then generates a specific _traversal_, which is the order of steps that will be taken to fulfill a specific request. 
+Fidesops uses your Datasets to generate a _graph_ of the resources. Based on the identity data you provide, f then generates a specific _traversal_, which is the order of steps that will be taken to fulfill a specific request. 


Fidesops accidentally replaced with f

conceptualshark · 2022-07-12T17:34:13Z

@pattisdr thank you for the review and catching the lingering Fidesops uses! Should be good to go on those changes. 👍

pattisdr

🎉

* copy changes to fix docs outlining [#427] and standardize formatting [DOX-216]

Cole Isaac added 3 commits July 11, 2022 16:44

copy changes to fix docs outlining [#427] and standardize formatting …

f3e0777

…[DOX-216]

Merge branch 'main' into cg-organization-overhaul

ed6c42b

correct changelog

8566321

conceptualshark marked this pull request as ready for review July 11, 2022 20:59

seanpreston reviewed Jul 12, 2022

View reviewed changes

Cole Isaac added 2 commits July 12, 2022 10:17

style guide feedback

727b990

changelog conflict

4c7f39c

seanpreston self-assigned this Jul 12, 2022

seanpreston requested a review from pattisdr July 12, 2022 15:16

pattisdr reviewed Jul 12, 2022

View reviewed changes

typos, feedback

d1dcd78

conceptualshark requested a review from pattisdr July 12, 2022 17:34

pattisdr approved these changes Jul 12, 2022

View reviewed changes

conceptualshark merged commit 51f42f5 into main Jul 12, 2022

conceptualshark deleted the cg-organization-overhaul branch July 12, 2022 19:05

sanders41 pushed a commit that referenced this pull request Sep 22, 2022

documentation reorganization and page standardization (#858)

98b402a

* copy changes to fix docs outlining [#427] and standardize formatting [DOX-216]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

documentation reorganization and page standardization #858

documentation reorganization and page standardization #858

conceptualshark commented Jul 11, 2022 •

edited

seanpreston Jul 12, 2022 •

edited

conceptualshark Jul 12, 2022

pattisdr left a comment

pattisdr Jul 12, 2022

pattisdr Jul 12, 2022

pattisdr Jul 12, 2022

pattisdr Jul 12, 2022

pattisdr Jul 12, 2022

pattisdr Jul 12, 2022

conceptualshark commented Jul 12, 2022

pattisdr left a comment

		@@ -89,4 +89,4 @@ In order to submit code to Fidesops, please:

documentation reorganization and page standardization #858

documentation reorganization and page standardization #858

Conversation

conceptualshark commented Jul 11, 2022 • edited

Purpose

Changes

Checklist

Ticket

seanpreston Jul 12, 2022 • edited

Choose a reason for hiding this comment

conceptualshark Jul 12, 2022

Choose a reason for hiding this comment

pattisdr left a comment

Choose a reason for hiding this comment

pattisdr Jul 12, 2022

Choose a reason for hiding this comment

pattisdr Jul 12, 2022

Choose a reason for hiding this comment

pattisdr Jul 12, 2022

Choose a reason for hiding this comment

pattisdr Jul 12, 2022

Choose a reason for hiding this comment

pattisdr Jul 12, 2022

Choose a reason for hiding this comment

pattisdr Jul 12, 2022

Choose a reason for hiding this comment

conceptualshark commented Jul 12, 2022

pattisdr left a comment

Choose a reason for hiding this comment

conceptualshark commented Jul 11, 2022 •

edited

seanpreston Jul 12, 2022 •

edited