From 27014e647d1648ebb2c3fcc82072d6a24bd4c580 Mon Sep 17 00:00:00 2001 From: Dan Moore Date: Fri, 18 Aug 2023 10:36:03 -0600 Subject: [PATCH] Revise docsdevreadme for new world (#2471) * Revise docsdevreadme for new world * emphasized header stuff --- DocsDevREADME.md | 210 ++++++++++++++++------------------------------- 1 file changed, 72 insertions(+), 138 deletions(-) diff --git a/DocsDevREADME.md b/DocsDevREADME.md index 4042874bce..dfa39eb37d 100644 --- a/DocsDevREADME.md +++ b/DocsDevREADME.md @@ -1,34 +1,41 @@ -## Documentation Style Guidelines +## Content Style Guidelines -Here are some guidelines to follow when writing documentation (everything under `/site/docs`) as well as the blog (`_posts`). +Here are some guidelines to follow when writing documentation (everything under `/site/docs`), articles, and blogs (`astro/src/content/blog`). - Capitalize all domain objects, especially when working the object's API in which it is created and updated in FusionAuth. For example, see the API Key APIs description for `apiKeyId`, where API Key is capitalized: `The unique Id of the API Key to create. If not specified a secure random UUID will be generated.` - If referring to something that exists as a domain object in FusionAuth, but you are not explicitly referring to an object being created/updated in FusionAuth, use lowercase. Here are some examples: `To allow users to log into and use your application, you’ll need to create an Application in FusionAuth.` - From the Link API, note the difference between a FusionAuth User and a 3rd party user: `This API is used to create a link between a FusionAuth User and a user in a 3rd party identity provider. This API may be useful when you already know the unique Id of a user in a 3rd party identity provider and the corresponding FusionAuth User.` - Do not manually wrap long lines. Use the soft wrap in your editor to view while editing. -- Use `Id` instead of `ID` when describing a unique identifier +- Use `Id` instead of `ID` or `id` when describing a unique identifier - Use `logged in` instead of `logged-in` - `log in` is the verb, `login` is the noun -- Don't use complex breadcrumbs styling. Use `->` because Asciidoc converts this to a nice Unicode arrow. Breadcrumbs should look like this `[breadcrumb]#foo -> bar -> baz#` -- If you are referencing a URL as a setting and don't want it to be hyperlinked, preface it with a `\`. For example: `\https://fusionauth-example.zendesk.com` -- If you are referencing a field in a form or JSON API doc, use the `[field]` class (rather than backticks): `[field]#Issuer#` -- If you are referencing a UI element or button, use the `[uielement]` class: `Click the `[uielement]#Ok# button` in docs. - Don't abbreviate FusionAuth, use the full name. -- When you have a list of values, use this phrase to prefix it: "The possible values are:" -- When using images that are cropped, add `top-cropped` and/or `bottom-cropped` roles as appropriate. Use `box-shadow` only when an image isn't captured in the manner documented below. It's used only when we have screenshots of things that do not have a box shadow and are all white and blend in too much with our white background. No other image classes are needed when creating documentation. -- In general, put screenshot images after the text describing the image. That is "This functionality....\n\n". However, when describing fields for screens, as in the core concepts section, put the screenshot first. -- References to `http://127.0.0.1` should be updated to `[http://localhost` and remove hyperlinks to `localhost` +- References to `http://127.0.0.1` should be updated to `http://localhost`. Remove hyperlinks to `localhost`. - Always provide an alt text for images. It should always be a full sentence describing the content of the image. +- In general, put screenshot images after the text describing the image. That is "This functionality....\n\n". However, when describing fields for screens, as in the core concepts section, put the screenshot first. - If possible use an SVG for images. Otherwise a PNG that has been properly minified is acceptable. - Never use the term GUID, it's always UUID. If you mention any, display them in `8-4-4-4-12` format: `631ecd9d-8d40-4c13-8277-80cedb8236e3` -- Include fragments that are shared between different sections of the doc should be stored in the `shared` directory. -- All `link`s should be fully-qualified and never include a slash at the end (i.e. `link:/docs/v1/tech/apis/users` not `link:users`) -- All code snippets within any documents should have indenting formatted to 2 spaces. - When introducing a code snippet, don't use a : (colon). Instead, just use verbiage before it. "The code to exchange the token is similar to below." - Prefer 'You' to 'We'. 'Let's' is acceptable. -- Code captions should have the the first letter of every word should be capitalized, except for a, an and the: This Code Is The Best. +- All code snippets within any documents should have indenting formatted to 2 spaces. +- Code captions should have the the first letter of every word should be capitalized: This Code Is The Best. +- All image captions should be one or more complete sentences. - Use the oxford comma. Apples, bananas, and oranges are my favorite fruits. +- Single spaces should be used instead of double spaces after a period. +- Headers should have the first letter of every word capitalized: `This Is The Header Text`. This is true for all headers (h1, h2, h3, h4). + (quick check is: `grep '^## \([^ ].*\)\{0,1\}' site/_posts/.md`) +- When writing, you have access to Asides. Here's an [example blog post using an Aside](https://github.com/FusionAuth/fusionauth-site/blob/master/astro/src/content/blog/log4j-fusionauth.mdx). You can assign the following values to the type: `tip` for tips. `note` for things for the user to be aware of. `important` for things the user should pay attention to. `warn` for dangerous actions like deleting a tenant. + +## Docs +- Don't use complex breadcrumbs styling in docs. Use `->` because Asciidoc converts this to a nice Unicode arrow. Breadcrumbs should look like this `[breadcrumb]#foo -> bar -> baz#`. When using markdown, use `foo -> bar -> baz{:breadcrumb}` +- If you are referencing a URL as a setting and don't want it to be hyperlinked, preface it with a `\`. For example: `\https://fusionauth-example.zendesk.com` +- If you are referencing a field in a form or JSON API doc, use the `[field]` class (rather than backticks): `[field]#Issuer#` in asciidoc or `Issuer in markdown. +- If you are referencing a UI element or button, use the `[uielement]` class: `Click the `[uielement]#Ok# button` in asciidoc or `Issuer in markdown. +- When you have a list of values, use this phrase to prefix it: "The possible values are:" +- When using images that are cropped, add `top-cropped` and/or `bottom-cropped` roles as appropriate. Use `box-shadow` only when an image isn't captured in the manner documented below. It's used only when we have screenshots of things that do not have a box shadow and are all white and blend in too much with our white background. No other image classes are needed when creating documentation. +- Include fragments that are shared between different sections of the doc should be stored in the `shared` directory. +- All `link` elements should be fully-qualified and never include a slash at the end (i.e. `link:/docs/v1/tech/apis/users` not `link:users`) - If something is new in a version, mark it with something like this: [NOTE.since] @@ -36,9 +43,7 @@ Here are some guidelines to follow when writing documentation (everything under Available Since Version 1.5.0 ==== -- If updating an article, please add a meta tag of updated_date: `YYYY-MM-DD` (as opposed to updating the date on the markdown file) - -- If a doc gets long consider adding a table of contents in the top section or breaking it into multiple documents. To generate a table of contents from section headers, run this script: +- If a doc gets long add a table of contents in the top section or break it into multiple documents. To generate a table of contents from section headers, run this script (replacing the `doc.adoc` value). Don't include the link to the section containing the TOC. ``` egrep '^[=]+ ' site/docs/v1/tech/doc.adoc |sed 's/=//' |sed 's/=/*/g'|sed 's/* /* <>/' ``` @@ -70,7 +75,6 @@ egrep '^[=]+ ' site/docs/v1/tech/doc.adoc |sed 's/=//' |sed 's/=/*/g'|sed 's/* / ### Including files - - If you are building a file to include across multiple sections of documentation, make sure you preface the filename with `_` and use dashes to separate words: `_login-api-integration` not `_login_api_integration`. - If you are including a file in the docs which uses asciidoctor, do not prepend the include file path with `/`. - If it is a top level doc, use the full path: `include::docs/v1/tech/samlv2/_saml_limitations.adoc[]`. Otherwise you will get `WARNING: include file is outside of jail; recovering automatically` messages. @@ -78,6 +82,8 @@ egrep '^[=]+ ' site/docs/v1/tech/doc.adoc |sed 's/=//' |sed 's/=/*/g'|sed 's/* / - If you accidentally do this, you can find the files where the issue is by running: `bundle exec jekyll build --verbose > outfile 2>&1` and then looking through `outfile` for the `WARNING`. The file just before the warning line will be the one with an issue. - If a doc pulls code from an example application, use the include directive against the raw github repo. You can also pull sections with tags or line numbers: `include::https://raw.githubusercontent.com/FusionAuth/fusionauth-example-node/master/package.json[]` or `include::https://raw.githubusercontent.com/FusionAuth/fusionauth-example-node/master/routes/index.js[tags=clientIdSecret]` +This will be revised when docs are migrated. + ### For API docs - We have many APIs which return the same objects either singly (if called with an Id) or in an array (if called without an Id). If you are creating or modifying an API with this, see if you can use the -base pattern that the tenants and applications do to reduce duplicates. - `Defaults` is always capitalized. @@ -85,11 +91,13 @@ egrep '^[=]+ ' site/docs/v1/tech/doc.adoc |sed 's/=//' |sed 's/=/*/g'|sed 's/* / ``` This field is required when [field]#theOtherField.enabled# is set to true. ``` -- If a feature is only available when using a paid edition, use the `shared/_premium-edition-blurb-api.adoc` fragment for API fields, and `shared/_premium-edition-blurb.adoc` for any other location where the feature is mentioned in docs. Only mark the request API fields. -- If a feature is only available when using a enterprise edition, use the `shared/_enterprise-edition-blurb-api.adoc` fragment for API fields, and `shared/_enterprise-edition-blurb.adoc` for any other location where the feature is mentioned in docs. Only mark the request API fields with this. +- If a feature is only available when using a paid plan, use the `shared/_premium-edition-blurb-api.adoc` fragment for API fields, and `shared/_premium-edition-blurb.adoc` for any other location where the feature is mentioned in docs. Only mark the request API fields. +- If a feature is only available when using essentials, use the `shared/_advanced-edition-blurb-api.adoc` fragment for API fields, and `shared/_advanced-edition-blurb.adoc` for any other location where the feature is mentioned in docs. Only mark the request API fields with this. +- If a feature is only available when using enterprise, use the `shared/_enterprise-edition-blurb-api.adoc` fragment for API fields, and `shared/_enterprise-edition-blurb.adoc` for any other location where the feature is mentioned in docs. Only mark the request API fields with this. - If you are working in the `/api/identity-providers` folder there is a `README` there to help you understand the structure and layout of the documentation for the Identity Providers API. - If a field was deprecated in a version 30 versions ago (deprecated in 1.15, you are now at 1.45), you can remove it from the docs. + #### Request section layout This is general layout guidance for APIs that have `GET` and `POST` options: ``` @@ -113,58 +121,40 @@ Example response(s) ## Blog posts -TODO: revise for astro +Follow everything in the `Content Style Guidelines` section. -For blog posts: -- Indent all code with two spaces per level. -- The class used for images should be updated to `class="img-fluid"`. -- If applicable, use _includes/_what-is-fusionauth.liquid to introduce FusionAuth in a standard way. -- Single spaces should be used instead of double spaces after a period. +- If updating an blog post, please update the add a meta tag of updated_date: `YYYY-MM-DD` (as opposed to updating the date on the markdown file) +- If you have a common component that you want to include, make sure the blog is a `.mdx` file and create a component. [Example components](https://github.com/FusionAuth/fusionauth-site/tree/master/astro/src/components/blog) - [Example blog post using a component](https://github.com/FusionAuth/fusionauth-site/blob/master/astro/src/content/blog/amazon-cognito-and-fusionauth-comparison.mdx) +- Images should be pulled in using markdown: `![alt text](/path/to/images)` +- Images for a blog post should go under /astro/public/img/blogs/` in a directory related to the blog title. - We use rouge for code formatting. Supported languages are listed here: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/lexers -- Blog post headers should have the first letter of words in headers should be capitalized: This Is The Header Text - (quick check is: `grep '^## \([^ ].*\)\{0,1\}' site/_posts/.md`) - For site navigation, use double quotes: Navigate to "Tenants" and then to the "Password" tab. - For field names, use double quotes: "Login Identifier Attribute". - For values, use back ticks: `userPrincipalName`. -- If appropriate, use tags. Here are the following tag types. They are separated with spaces. These are freeform, so feel free to add multiple and choose what works. --- `client-` if the post refers to a specific language we have a client library for (use `client-javascript` for JS even though our client lib is typescript). These show up on the client libraries page. --- `tutorial` for tutorials. These show up on the tutorial page. --- `tutorial-`, `tutorial-` for a tutorial in a specific language or framework. --- `tutorial-feature` for a tutorial for a given feature (how to use a lambda, for example) --- `tutorial-integration` for a tutorial doing an integration with another software package (nodebb, for example) --- `topic-` for general topics. --- `topic-community-story` for any community stories you do. --- `feature-` for specific features. These will show up on the feature page. +- Put each blog post into one or more of the known categories. [Here's the list](https://github.com/FusionAuth/fusionauth-site/blob/master/.github/known-blog-categories.txt). You can separate categories with commas. +- Use tags. They are separated with commas. These are freeform, so feel free to add multiple and choose what works. The first one is what is used to show related posts, unless there's a `featuredTag` value in the front matter. You can [learn more about the logic by reviewing the layout](https://github.com/FusionAuth/fusionauth-site/blob/master/astro/src/layouts/Blog.astro). - You can use the `get-images-from-markdown.rb` script to extract images from markdown and store them in a directory. -- You can add a `related_resources` array of hashes to the front matter if you would like to customize the `additional resources` sidebar. See site/_posts/2022-10-27-introducing-biometric-authentication.md for format and example. - All references to `stackoverflow.com` should be updated and direct to the community forum at `https://fusionauth.io/community/forum/` -- When writing blog posts, you have access to callouts. - - ![callout-important](https://github.com/FusionAuth/fusionauth-site/assets/1877191/a6735cb8-17b2-44ee-9dda-cf374a750f1d) - ![callout-note](https://github.com/FusionAuth/fusionauth-site/assets/1877191/24a47f1e-5d42-46f3-959c-606a02ae93dc) - ![callout-tip](https://github.com/FusionAuth/fusionauth-site/assets/1877191/bbc710e3-58c9-42fb-b5b3-23ce242d38f4) - - - There are three callout liquid files `_callout-tip`, `_callout-important`, `_callout-note` - - They can be accessed as so: - ```markdown - {% include _callout-tip.liquid - content= - "" - %} - ``` -- Add each blog post to one of 6 categories: --- article: generic catch all type --- community story: community and customer stories --- comparison: an explicit comparison with another auth provider --- tutorial: a tutorial on how to do something --- announcement: a press release or release announcement --- feature: a post about a particular feature -- All captions should be one or more complete sentences. +- When using an aside in the blog, please use the `nodark="true"` attribute. ## Lists - Capitalize the first word. -- Have a period on the end if it is a sentence, otherwise don't. +- Have a period on the end if the list item is a sentence, otherwise don't. + +Examples. + +I like: + +- apples +- bananas +- blueberries + +Fruits were domesticated at different times. + +- Apples were domesticated 4000 years ago. +- Bananas were domesticated 3000 years before apples. +- Blueberries were not domesticated until around 1900. ## Proper names and other verbiage - .NET Core @@ -198,45 +188,25 @@ For blog posts: - X.509 - ## Words to avoid - etc -## Git - -* Open a PR with changes. Tag someone to review it. -* Merge using the GitHub interface or using a merge commit. -* Don't `push -f` in general. Unless you know what you are doing. - -## Tagging blog posts - -Tag your blog posts. - -If they feature any client libraries, tag them with `client-[langname]` and they will automatically appear on the client libraries page. `client-javascript` appears on the typescript page, since that is the supported client library. - -If they highlight a feature, tag them with `feature-[featurename]` and if there's a feature page, they'll appear there. `feature-breached-password-detection` for example. - -If they are a tutorial, add `tutorial` and they will appear on the tutorials page in the docs. You can also add `tutorial-[langname]` if it focuses on a language, `tutorial-feature` if it is a FusionAuth feature (webhooks, themes, etc) and `tutorial-integration` if it is an integration tutorial (nodebb, wordpress, etc). If it is for an advanced feature/reactor feature, add `tutorial-reactor-feature`. Those are all separate sections. +## Article workflow -If it is a community story, tag with `topic-commmunity-story`. Right now that doesn't do anything, but it will. +Varies, but you'll always want to -If it is a story about an upgrade, tag it with one of these tags: - -* `topic-upgrade-homegrown` -* `topic-upgrade-saas` -* `topic-upgrade-opensource` - -As well as the competitor name if mentioned: `topic-upgrade-cognito`. +* Open a PR with changes. Tag someone to review it. +* Merge using the GitHub interface or using a squash commit. -Separate tags with spaces: `topic-upgrade-homegrown topic-community-story` +Don't `push -f` in general. Unless you know what you are doing. -You can add free form tags without the topic, tutorial, or feature prefix. Those will be collated and a tag cloud will be created on each blog post. +Publishing happens whenever a commit or PR is merged to `master`. ## Sizing Window for Screenshots -When adding screenshots to the documentation, articles or blogs, use a normalized browser window size. The following apple Script should be used to build a consistent browser window. +When adding screenshots to the documentation, articles or blogs, use a normalized browser window size. The following apple Script should be used to build a consistent Safari browser window. Note that you must have at least `1100` pixels of screen height. If you do not, your dimensions will be skewed. Go to `System Preferences > Display` then choose `More Space` or the next selection up from your current selection to ensure you have enough space available. @@ -282,7 +252,7 @@ end tell ## Screenshot Standards - Use light mode when capturing screenshots -- In macOS **System Settings > Appearance** make sure _Allow wallpaper tinting in windows_ is turned _off_ +- In macOS **System Settings > Appearance** make sure _Allow wallpaper tinting in windows_ is turned _off_. - Make sure you set your `fusionauth-app.runtime-mode` to `production` unless documenting a feature only available in `development` mode. - Use `CMD`+`shift`+`4`+`space` to get the drop-shadow style screenshots - After sizing the window using the AppleScript, do not make the windows smaller in the Y axis. @@ -300,7 +270,7 @@ end tell - Use https://local.fusionauth.io and use the correct kickstart to add the Silicon Valley characters ( https://github.com/FusionAuth/fusionauth-example-kickstart/blob/master/fusionauth/kickstart-development.json ) - Make sure that the same character is used for every screenshot on a page (unless you are demonstrating a view from the admin and also user perspective) -## Shell script for capturing sceenshots +### Shell script for capturing sceenshots fa-screenshot.sh is located under `fusionauth-site/src/`. With this script you can automate following tasks: - Sizing and moving the Safari window - Capturing the screenshot @@ -340,33 +310,13 @@ that this parameter will drop and significantly reduce your file size (by about `-pix_fmt yuv420p` changes the pixel format to yuv420p which is the magic sauce that safari wants (this is also the part that needs a size that is divisible by 2) -## Adding a 'Related Posts' section - -You can add related blog posts to any of the docs pages. - -First add tags to the relevant blog posts. If it is a client library post, use the form `client-`. If it is an API related post, use `api-
`. If it is a feature, use `feature-`. - -Then, add the following directive to the top of the file: - -``` -:page-liquid: -``` - -Then, wherever you want the related posts to show up, add this text: - -``` -++++ -{% capture relatedTag %}api-tenants{% endcapture %} -{% include _doc-related-posts.liquid %} -++++ -``` +## Search -Update the `relatedTag` value to match the tag added to the blog post. +We use algolia to search jekyll content and pagefind to search astro content. +### Algolia -## Search - -We use algolia to search. This only searches content on the public site, so if you are running locally, it won't fully work. (It'll find local versions of public content, but not unpublished content.) +This only searches content on the public site, so if you are running locally, it won't fully work. (It'll find local versions of public content, but not unpublished content.) To do a dry run of the search indexing to see what will content be indexed on the next push: @@ -380,9 +330,13 @@ or, if you want to see everything: bundle exec jekyll algolia --dry-run --verbose ``` +### Pagefind + +This runs on the astro build. https://pagefind.app/ has more details + ## Docs navigation -We use a combination of URL and frontmatter metadata to determine what documentation section to hold open when you are visiting a doc page. +We use a combination of URL and frontmatter metadata to determine what documentation section to hold open when you are visiting a doc page. This is for the old jekyll site only. In general, set the `navcategory` frontmatter attribute to the correct value when adding a new documentation page. The only exception is the API docs, which all live under `/apis/` so we can use that path and don't have to set the `navcategory` value. @@ -418,20 +372,12 @@ The theme pages are kinda complex because they a data file which is iterated ove ### Adding an example app -* Create a repo. It should have the prefix `fusionauth-example-` and you should add both the owners (as admins) and developer team (as maintainers). +* Create a repo. It should have the prefix `fusionauth-example-` and you should add both the owner and devrel teams (as admins) and developer team (as maintainers). * Add a readme and a license (apache2). It's great for the readme to point at the blog post, but you can also update the readme after your post is live. * Add an entry in https://github.com/FusionAuth/fusionauth-site/blob/master/site/_data/exampleapps.yaml (you can do it on your blog post branch). Note that you can only put an app in one tech group, and that if it is a JavaScript app, use JavaScript, not typescript, as the group name. This will add the example app to the example apps section in the docs. -## Expert Advice - -The places to put files for the Expert Advice sections differ from the regular blog. -Content: `site/learn/expert-advice/security` # or other top level category
 -Images: `site/assets/img/advice/` -Stamps: `site/assets/img/stamps` -Diagrams: `site/_diagrams/learn/expert-advice/` - ## Documentation self-review checklist Prior to requesting review on a PR, please complete the following checklist. @@ -458,19 +404,7 @@ Prior to requesting review on a PR, please complete the following checklist. ## Content checklist -This is for substantial content. - -1. Create an [issue in fusionauth-site](https://github.com/FusionAuth/fusionauth-site/issues/new) -1. Write the piece. -1. Any screenshots should conform to screenshots standards outlined above. -1. Create a PR. Add the `content` label. -1. Ask another devrel to review it. Add them as a reviewer. If they don't review it in a timely fashion, ping them on slack. -1. Once it has been through tech review, send it through SEO review. Add an asana task, assign it to Brad, and put it under the SEO section in Asana. Put a due date of a week out. -1. Once it has been through SEO review, make any needed changes and then add it to the 'content calendar' asana board. Assign it to Emily so she can pick a publish date. -1. After a publish date has been set, she'll assign it back to you. -1. Publish it on that date. - -If the content is timely, you can skip some of these steps. Check with Dan or Emily about whether your content is timely. +TBD ## Quickstarts