Skip to content

Commit c472cff

Browse files
eric-schneidereric-schneider
authored
Post-unification updates (#47)
* Add unified docs assets * Resolve external-link-icon warnings * Delete old dispatch workflow
1 parent 5223905 commit c472cff

22 files changed

+687
-57
lines changed

‎.gitignore

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
1-
node_modules/
2-
package-lock.json
3-
build/
4-
.vscode/
5-
.DS_Store
1+
#OS
2+
**/.DS_Store
3+
**/.git-credentials
4+
5+
#IDE
6+
**/.vscode/
7+
**/.idea
8+
**/*.iml
9+
*.http
10+
**/.java-version
11+
12+
#build
13+
**/package-lock.json
14+
**/node_modules/
15+
/build/

‎README.adoc

Lines changed: 154 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,159 @@
1-
= streaming-learning-docs
1+
= {company} {product} Docs
2+
// Variables:
3+
:company: DataStax
4+
:product: Streaming Learning
5+
:repo-name: streaming-learning-docs
6+
:github-org: datastax
7+
// Settings:
8+
:toc: macro
9+
:!example-caption:
10+
:experimental:
11+
:hide-uri-scheme:
12+
ifdef::env-github[]
13+
:icons: font
14+
:toclevels: 1
15+
:toc-title: Contents
16+
:tip-caption: :bulb:
17+
:note-caption: :information_source:
18+
:important-caption: :heavy_exclamation_mark:
19+
:caution-caption: :fire:
20+
:warning-caption: :warning:
21+
:badges:
22+
endif::[]
23+
// Project URLs:
24+
:url-github-org: https://github.com/{github-org}
25+
:url-project-repo: {url-github-org}/{repo-name}
26+
:url-ui-repo: https://github.com/riptano/docs-ui
27+
:url-playbook-repo: https://github.com/riptano/datastax-docs-site
28+
:url-contribute:
29+
:url-datastax: https://datastax.com
30+
:url-datastax-docs: https://docs.datastax.com
31+
:url-docs-preview: http://docs-preview.datastax.com
32+
// External URLs:
33+
:asciidoc-language: https://docs.asciidoctor.org/asciidoc/latest/
234

3-
== Writing a guide
35+
This repository contains the source files for the {company} {product} documentation.
436

5-
A guide is a document offering step by step instruction to reach some goal. Guides are technical in nature and tend to make assumptions about the consumer's environment. To help create guides that will work in most environments, please follow these ideas.
37+
toc::[]
638

7-
* *Keep links to a minimum* - when someone is learning a new concept for the first time and xref:README.adoc[every] other xref:README.adoc[word] is linked it xref:README.adoc[makes] things xref:README.adoc[confusing] and hard to get a good flow going. Instead, annotate a word or phrase and provide a "Resources" area at the bottom of the guide.
8-
* *Separate products and runtimes in tabs* - it is common to reach the same result through multiple ways. An example is creating a tenant/namespace/topic in Astra Streaming and Luna Streaming. Both have the same result but get there in very different ways. Offer each as a tab and let the consumer choose their path. The step after the tabbed step can assume the consumer has complete the previious step and is in a known state. Runtimes follow the same pattern. Weather one is using Java or C#, they are still creating a Pulsar client to interact with the cluster. Create a single step in the guide with multiple tabs for each runtime.
9-
* *Be thoughtful about the names you use* - if you are leaning a new concept or feature with no background on the product, words matter. Labeling a tab as "Luna Helm" and then referring to it as "Pulsar Helm Chart" are two distinct things to that reader. The author of the document has such deep understanding that they consider those things the same - and technically they are at DataStax. But the read isn't from DataStax, so be mindful of their context.
10-
* *Talk in first person* - humans create the guides and humans consume the guides. Write as if you are paired with your consumer in doing what ever the guide does. Use "we", "us", "you".
39+
== Get started
1140

12-
=== Starter example
41+
The documentation is written in {asciidoc-language}[AsciiDoc]-formatted source files located in the `modules` directory.
1342

14-
Create a new .adoc file in the appropriate module and use the `example-guide.adoc` file as a starting point to creating a new guide.
43+
=== Make a simple update
44+
45+
For simple updates like fixing typos or modifying existing prose, it's easiest to edit the source files directly on GitHub.
46+
47+
NOTE: You'll need Write privileges on the repository to edit files directly on GitHub.
48+
49+
. Find the file you want to edit in the `modules` directory.
50+
51+
. Click the *Edit* icon in the upper-right corner of the file view.
52+
53+
. Make your changes in the editor.
54+
55+
. Click *Commit changes...*
56+
57+
. Enter a description for your commit and click *Propose changes*.
58+
59+
. On the *Open a pull request* screen, enter a title and description for your change, assign reviewers, then click *Create pull request*.
60+
61+
. Once the pull request is open, an automatic draft preview build is triggered.
62+
Once complete, the build system posts a comment on the pull request with a link to the draft site for you to preview your changes.
63+
64+
=== Edit docs locally
65+
66+
If you need to make substantial updates to the documentation, you'll want to clone the repository so you can work with the source files locally.
67+
68+
. Clone this repository
69+
+
70+
[source,bash,subs="attributes"]
71+
----
72+
git clone {url-project-repo}.git
73+
----
74+
75+
. https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic[Create a _classic_ personal access token] for your GitHub account.
76+
When configuring the token, set the *Expiration* to at least 90 days and select everything under the *Repo* https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes[scope].
77+
+
78+
[IMPORTANT]
79+
====
80+
Copy your personal access token to a temporary location -- you'll need it later.
81+
====
82+
83+
. https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on[Authorize your personal access token] so that it can access repositories in the Riptano and DataStax organizations in GitHub.
84+
85+
. https://docs.antora.org/antora/latest/playbook/private-repository-auth/#populate-credentials-directly[Populate the credential store] with your personal access token.
86+
For most people this means doing the following:
87+
+
88+
.. Create the file `$HOME/.git-credentials` and open it in your editor.
89+
.. Add the following line:
90+
+
91+
[source,subs="verbatim,quotes"]
92+
----
93+
https://**TOKEN**:@github.com
94+
----
95+
+
96+
Replace *`TOKEN`* with the personal access token you copied from GitHub.
97+
.. Save and close the file.
98+
99+
. If you don't already have Node.js installed, do the following:
100+
101+
.. Install https://github.com/nvm-sh/nvm[nvm].
102+
+
103+
If you're on macOS, you can install nvm using https://brew.sh/[Homebrew]:
104+
+
105+
[source,bash]
106+
----
107+
brew install nvm
108+
----
109+
110+
.. Use nvm to install Node.js.
111+
+
112+
[source,bash]
113+
----
114+
nvm install --lts
115+
----
116+
+
117+
[source,bash]
118+
----
119+
nvm use --lts
120+
----
121+
+
122+
[source,bash]
123+
----
124+
nvm alias default node
125+
----
126+
127+
. Install the project dependencies.
128+
+
129+
[source,bash,subs="attributes"]
130+
----
131+
cd {repo-name}
132+
----
133+
+
134+
[source,bash]
135+
----
136+
npm install
137+
----
138+
139+
. Build the site.
140+
+
141+
[source,bash]
142+
----
143+
npm run build:local
144+
----
145+
+
146+
If the build was successful, you'll see the following output in your terminal:
147+
+
148+
[source,console,subs="attributes"]
149+
----
150+
Site generation complete!
151+
Open file:///Users/USERNAME/repos/{repo-name}/build/site/index.html in a browser to view your site.
152+
----
153+
+
154+
To view the site, paste the entire `\file:///` path into your browser's address bar and press kbd:[Return].
155+
156+
[#publish-docs]
157+
== Publish docs
158+
159+
To learn how to publish documentation to {url-datastax-docs}, see the {url-playbook-repo}#deploy-production[datastax-docs-site README].

‎example-guide.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,17 @@
33
:description: This guide will take you step-by-step through implementing this new feature
44
:title: A guide to creating a new feature
55

6+
.About writing a guide
7+
[TIP]
8+
====
9+
A guide is a document offering step by step instruction to reach some goal. Guides are technical in nature and tend to make assumptions about the consumer's environment. To help create guides that will work in most environments, please follow these ideas.
10+
11+
* *Keep links to a minimum* - when someone is learning a new concept for the first time and xref:README.adoc[every] other xref:README.adoc[word] is linked it xref:README.adoc[makes] things xref:README.adoc[confusing] and hard to get a good flow going. Instead, annotate a word or phrase and provide a "Resources" area at the bottom of the guide.
12+
* *Separate products and runtimes in tabs* - it is common to reach the same result through multiple ways. An example is creating a tenant/namespace/topic in Astra Streaming and Luna Streaming. Both have the same result but get there in very different ways. Offer each as a tab and let the consumer choose their path. The step after the tabbed step can assume the consumer has complete the previious step and is in a known state. Runtimes follow the same pattern. Weather one is using Java or C#, they are still creating a Pulsar client to interact with the cluster. Create a single step in the guide with multiple tabs for each runtime.
13+
* *Be thoughtful about the names you use* - if you are leaning a new concept or feature with no background on the product, words matter. Labeling a tab as "Luna Helm" and then referring to it as "Pulsar Helm Chart" are two distinct things to that reader. The author of the document has such deep understanding that they consider those things the same - and technically they are at DataStax. But the read isn't from DataStax, so be mindful of their context.
14+
* *Talk in first person* - humans create the guides and humans consume the guides. Write as if you are paired with your consumer in doing what ever the guide does. Use "we", "us", "you".
15+
====
16+
617
Have you ever wanted to use this new feature? Well look no further than this guide to get started. We will be implementing it from scratch and you will find a set of links at the bottom to continue use of the feature.
718

819
== Pre-req's

0 commit comments

Comments
 (0)