技术文档写作常用工具大全

1. GitHub desk top - https://desktop.github.com/

Git cli - git-scm.com/downloads (optional)

版本控制和文档代码托管库。

2. Visual Studio Code https://code.visualstudio.com/Download After installation, install the following VSC extensions.

写作 markdown 文档的编辑器，非常强大易用。

3. Acrolinx: https://marketplace.visualstudio.com/items?itemName=acrolinx.vscode-sidebar

昂贵的语法检查器，但非常好用，省去了人工校对。

4. Code Spell Checker: https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker

The goal of this spell checker is to help catch common spelling errors while keeping the number of false positives low.

5. VS code icons (OPTIONAL but handy): https://marketplace.visualstudio.com/items?itemName=vscode-icons-team.vscode-icons

It displays different icons for folders, files, and so on, handy to differentiate them.

6. Markdown Preview Enhanced (After installation, open your MD file in VSC, open the command palette using CTRL SHIFT an P, enter “Preview”, select Preview - > Open preview to the side)

写完文档先预览下再发布。

7. Other useful VS code extensions: Highlight Matching Tag, auto close tag, trailing spaces, and highlight trailing white spaces.

8. marked-it-cli for local builds from markdown files to html files.

Mac example: marked-it-cli /Users/xxx/Documents/Github/docs/ --output=/Users/xxx/Documents/Github/output --conref-file=/Users/xxx/Documents/Github/docs/conrefs.yml --toc-xml --overwrite --verbose

Windows example: marked-it-cli C:\Users\xxx\Documents\GitHub\xxx\xxx --output=C:\Users\xxx\Documents\abuild_output --conref-file=C:\Users\xxx\Documents\GitHub\xxx\conrefs_cp.yml --toc-xml --overwrite --verbose

9. Broken Link Checker

Linux:

a. Install Filezilla. Use Filezilla to copy the md files or folders to Linux. For example, copy the document folder to the /var/tmp directory.

b. Run the commands in Linux one by one:

cd /var/tmp

find . -name "*.md" -exec markdown-link-check -q {} \; > ../filename.txt

c. Find the filename.txt in /var folder. Run the command to see the broken link checking results.

cd ../

cat filename.txt

d. You can also copy the filename.txt file to your local Windows machine via Filezilla.

Mac:

a. From the terminal application run the following command to install the link check tool:

npm install -g markdown-link-check

b. To run broken links against the documentation change to the directory where the docs repository is copied on your machine in the Terminal application. Example: cd ~/Documents/GitHub/docs

c. Run the link check tool from the Terminal Application by running the following command:

find . -name "*.md" -exec markdown-link-check -q {} \;

d. To create a file with the recorded output, run the following command from the Terminal :

find . -name "*.md" -exec markdown-link-check -q {} \; > ../filename.txt

10. Spell checker

Windows：

a. Download and install npm if not installed already. This link https://nodejs.org/en/download/current/ directs you to system downloads for npm.

b. After you download the installer. Double-click the installer and follow the instructions ( You can use the default settings). If you encounter problems you can use the package installer and follow the instructions on the nodejs.org site.

c. To verify nodejs and npm are installed, open a command-line as an administrator and run "node -v". The version should be at least "v8.12.0"

d. Then, run "npm -v". The version should be at least "v6.9.0"

e. After installation, you can run the commands from the command-line (see above commands) or create desktop shortcuts to run the spellcheck tool, broken links tool, and local build. To create shortcuts:

Right-click on your desktop. Select New > Shortcut.

For the "Type the location of the item:" enter one of the following:

- For Spellcheck tool

C:\Windows\System32\cmd.exe /k mdspell -r -n -a --en-us *.md **/*.md **/**/*.md **/**/**/*.md > ../yourfilename.txt

- For local build

C:\Windows\System32\cmd.exe /k marked-it-cli /Users/YourUserName/Documents/GitHub/docs/ --output=/Users/YourUserName/Documents/GitHub/output --conref-file=/Users/YourUserName/Documents/GitHub/docs/conrefs.yml --toc-xml --overwrite --verbose

Mac:

Steps to install and run Markdown SpellCheck.

a. From the Terminal application run the following command to install the spellcheck tool:

npm i markdown-spellcheck -g

b. Change to the directory where the docs repository is copied on your machine in the Terminal application to run spellcheck against the documentation,.

Example: cd ~/Documents/GitHub/docs

c. Run the spell check tool from the Terminal Application by running the following command:

mdspell -r -n -a --en-us *.md **/*.md **/**/*.md **/**/**/*.md > ../yourfilename.txt

d. Click Next.

e. Enter a name for your command. Then, click Finish.

f. Right-click your new desktop shortcut and click Properties.

g. For the Start in: field replace any default path with the path to where the command needs to run. This is the location where you installed your docs repo/npm. Alternatively, you can include everything in the location - I just did it this way :)

- For Spellcheck tool

C:\Users\YourUserName\Documents\GitHub\xxx\docs

- For local build

Location includes path to directory to run the command.

h. Double-click the shortcut to run the command ( a command-line window opens and when the process is completed, show the path to the specified start in location. For a local build the running build also displays.

i. Check your specified destination for the resulting files ( either your root Docs folder or your output folder).

11. CHKPII https://w3-03.ibm.com/globalization/page/2011

检查 PII compliance。

12. Jenkins

Contest: You want to build your default branch and publish the pre-production KC.

1. Log in Jenkins with your GSA user and password.

2. Select "Build with parameters" in the left navigation panel.

3. Enter the following properties file path in the "PRODUCT_CONFIG" field.

/gsa/XXX/xxx.properties

4. Click "Build".

5. Click “#build_number” under Build History panel and then check the building result by clicking “Console Output”.

6. If there are no errors in the console output and you see the result “Finished: Success”, you can view the updated content in pre-production KC.

xxx.properties 文件：

product = <KC展示的产品名>

path = ../../../platform/xxx/xxx

toc = xxx.ditamap or SUMMARY.md

# <git_repo_location> is the main product repo, such as github.xxxcom/xxx/xxx-docs.git

git.url = git@<git_repo_location>

git.branch = <branch_name>

# common services repo

git.url.common = git@github.xxx.com/xxx/xxx-docs.git

git.branch.common = master

# second git repo to pull in

# git.url.second = git@github.xxx.com:second.git

# git.branch.second = second

conref = conrefs_cp.yml

13. Chrome 里用 Dynamic Assessment Plugin 插件检查 accessibility.

步骤：

a. Open Chrome

b. Go to the Dynamic Assessment Plugin in the Chrome Web Store.

c. Click Add To Chrome.

First Scan:

a. Go to the Tools page and click the Copy Authentication Token button.

b. In the Chrome Menu, select More Tools > Developer Tools

c. The Elements panel should automatically open. The Elements panel is associated with multiple subpanels, such as Styles. Select DAP near the end of the subpanel list

d. If you have not activated the authentication token or selected a ruleset, a message will indicate that you need to open the Options. Click the Options link in that message. In the Options page, paste the authentication token that you copied in step 1 and then choose one or more rulesets.

e. In the Rule Archive section, Enable rule archive option can be checked to enable rule archive selection. By default, the latest rule archive will be selected.

f. After you complete the above step, scanning should begin automatically. If the scan does not happen automatically, or if you want to scan again, click the Start Scan button.

The Report:

a. If the page contains multiple frames, each frame will be represented by a tab in the report.

b. Levels of accessibility violation are listed in the report. For each level of violation, you can remove it from the report by deselecting its check box. The levels of accessibility violation are:

- Violation: Automatically-detectable violations of the standard

- Potential Violation: Likely a violation, but requires manual review.

- Recommendation: Best practice recommendations.

- Manual Checks: Prompts to perform manual checking.

c. Issues are grouped by violation level. Expand the violation level groupings to see individual violations or issues within them. When you select an issue within a grouping, the Elements section displays the content of the selected violation.

Related help is available by pressing the question mark (?) at the end of each issue grouping.