Skip to content

Commit

Permalink
Corrected some typos.
Browse files Browse the repository at this point in the history
  • Loading branch information
wongyah committed Oct 24, 2024
1 parent d053151 commit e75200d
Showing 1 changed file with 26 additions and 26 deletions.
52 changes: 26 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ Markdown is a lightweight markup language created by John Gruber in 2004. It has

If you are completely new to Markdown, the following **📔 guide** is the best starting point for you:

- [Markdown Guide](https://www.markdownguide.org/) - Concise, barebones guide for Markdown beginners.
- [Markdown Guide](https://www.markdownguide.org/) - Concise, bare-bones guide for Markdown beginners.
- [John Gruber's Markdown Documentation](https://daringfireball.net/projects/markdown/)

Now, you know a bit about Markdown 👏. It is easy-to-read, easy-to-write, and easy-to-learn, isn't it 😎?
Expand All @@ -155,18 +155,18 @@ Can't wait to try it out? Just adopt a **✒️ Markdown editor**, then you are
- [Visual Studio Code (VS Code)](https://code.visualstudio.com/) - Code editor developed by Microsoft, with built-in Markdown preview and many Markdown extensions.
- [Markdown All in One](https://github.com/yzhang-gh/vscode-markdown/#readme) - An extension to enrich Markdown features in VS Code, such as automatic creation of table of contents, auto completions, printing Markdown files to HTML.
- [Markdown Table Maker](https://github.com/kaisugi/vscode-markdown-tablemaker?tab=readme-ov-file#readme) - An extension to generate Markdown tables in an easy and intuitive way.
- [Markdown PDF](https://github.com/yzane/vscode-markdown-pdf#readme) - An extenstion to convert Markdown files to PDF, PNG, JPEG, or HTML.
- [Markdown PDF](https://github.com/yzane/vscode-markdown-pdf#readme) - An extension to convert Markdown files to PDF, PNG, JPEG, or HTML.
- [Markdown Preview Enhanced](https://github.com/shd101wyy/markdown-preview-enhanced#readme) - An extension to enrich Markdown features in Atom and VS Code, featuring the integration of Pandoc.

If you go deeper, you will find [the controversy over Markdown](https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/).

As Markdown got popular, more and more Markdown parsers appeared. However, Markdown has no well-accepted standard untill now. The Markdown syntax in each parser is to some extent different from others.
As Markdown got popular, more and more Markdown parsers appeared. However, Markdown has no well-accepted standard until now. The Markdown syntax in each parser is to some extent different from others.

As a result, whenever you select a new Markdown tool, you must read through its **📙 user manual or documentation** to know exactly what Markdown syntax it supports.

- [GitHub Docs: Writing on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) - Basic Markdown syntax supported on GitHub.
- [GitHub Flavored Markdown Specification](https://github.github.com/gfm/)
- [Markdown DITA Syntax](https://www.dita-ot.org/dev/reference/markdown/markdown-dita-syntax) - Markdown styntax supported by DITA Open Toolkit, which is the most commonly used engine for DITA publishing.
- [Markdown DITA Syntax](https://www.dita-ot.org/dev/reference/markdown/markdown-dita-syntax) - Markdown syntax supported by DITA Open Toolkit, which is the most commonly used engine for DITA publishing.
- [MDITA Syntax](https://www.dita-ot.org/dev/reference/markdown/mdita-syntax) - Markdown syntax for Lightweight DITA supported by DITA Open Toolkit, which is the most commonly used engine for DITA publishing.
- [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) - Markdown syntax of Pandoc, a universal document converter, which can convert between various formats.
- [kramdown Quick Reference](https://kramdown.gettalong.org/quickref.html) and [kramdown Syntax](https://kramdown.gettalong.org/syntax.html) - Markdown syntax of kramdown, which is the default Markdown parser for Jekyll.
Expand All @@ -190,17 +190,17 @@ Now, you know a bit about reStructuredText 👏. Just adopt a **✒️ reStructu
- [reStructuredText](https://github.com/vscode-restructuredtext/vscode-restructuredtext#readme) - An extension to provide rich reStructuredText language support in VS Code.
- [reStructuredText Syntax Highlighting](https://github.com/trond-snekvik/vscode-rst#readme) - An extension to provide rich syntax highlighting and non-intrusive section navigation for reStructuredText in VS Code.

You may forget an infrequently used syntax or not sure about a specific syntax during writing. Pick a **📔 cheatsheet or reference documentation** at hand, which you will look for sooner or later.
You may forget an infrequently used syntax or not sure about a specific syntax during writing. Pick a **📔 cheat sheet or reference documentation** at hand, which you will look for sooner or later.

- [Quick reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) - Online cheatsheet for reStructuredText syntax.
- [reStructuredText Cheatsheet](https://github.com/ralsina/rst-cheatsheet#readme) - Downloadable two-page cheatsheet for reStructuredText syntax.
- [Quick reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) - Online cheat sheet for reStructuredText syntax.
- [reStructuredText Cheatsheet](https://github.com/ralsina/rst-cheatsheet#readme) - Downloadable two-page cheat sheet for reStructuredText syntax.
- [reStructuredText Markup Specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html) - Detailed technical specification for reStructuredText, authored by David Goodger.

### DITA

DITA is an open source standard for creating topic-based strcutured technical documentations, which was originally created by IBM and was donated to OASIS in 2004.
DITA is an open source standard for creating topic-based structured technical documentations, which was originally created by IBM and was donated to OASIS in 2004.

DITA was initially spread to high-tech companies like Adobe, Siemens, and Kone, and then become more and more popular in all industries.
DITA was initially spread to high-tech companies like Adobe, Boeing, Siemens, and Nokia, and then become more and more popular in all industries.

If you are completely new to DITA, the following **🔔 courses and tutorials** are the best starting points for you:

Expand All @@ -212,43 +212,43 @@ Now, you know a bit about DITA 👏. It's time to practice 💃🕺!

That said, DITA is a bit complicated. Adopt a [DITA-aware XML editor](https://www.ditawriter.com/list-of-dita-optimized-editors/) first, in case you are trapped in the tremendous DITA elements. Then, keep a **📙 book of DITA best practices** at hand for reference at any time.

- [DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA](https://www.amazon.com/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522) - A practical book about how to write effective technical information in DITA, published in 2011 by IBM Press (not a free resource).
- [DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA](https://www.amazon.com/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522) - A practical book about how to write effective technical information in DITA, published in 2011 by IBM Press (paid resource).
- [The DITA Style Guide: Best Practices for Authors](https://www.oxygenxml.com/dita/styleguide/) - Written in DITA 1.1 by Tony Self.
- [Jorsek's Technical Content Development Guide](https://github.com/Jorsek/jorsek-cdg) - Developed by the maker of the CCMS Heretto.
- [Jorsek's Technical Content Development Guide](https://github.com/Jorsek/jorsek-cdg) - Developed by the maker of Heretto CCMS.
- [Oxygen XML Author使用指南](https://github.com/EstelleRao/zh-oxygenxml-userguide) - A practical DITA migration guide in Chinese for technical documentation teams that are new to DITA and Oxygen XML Author.

You can use DITA to improve your own technical documentation. If you don't have such resources, pick one of **📔 open source sample manuals written in DITA** to see how it was written and think how to improve it.

- [DITA Mini Manual](https://github.com/flicstar/DITA-Mini-Manual#readme) - Mini owner's manual that published in 1960s rewritten in DITA.
- [Pilot Training Mitchell Bomber](https://github.com/DITAWriter/pilot_training_mitchell_bomber#readme) - A pilot training manual (aviation document) rewritten in DITA.
- [LwDITA Code Samples](https://github.com/DITAWriter/LwDITA_Code_Samples#readme) - Various manuals of a 1970s computer rewritten in Lightweight DITA.
- [DITA Glossary Example](https://github.com/DITAWriter/dita_glossary_example#readme) - A book named *On Yacht Sailing* rewritten in DITA to demontrate how to implement glossories.
- [DITA Glossary Example](https://github.com/DITAWriter/dita_glossary_example#readme) - A book named *On Yacht Sailing* rewritten in DITA to demonstrate how to implement glossaries.
- [DITA Style Guide](https://github.com/hyperwrite/DITAStyleGuide) - Source code for The DITA Style Guide: Best Practices for Authors, written by Tony Self.
- [BTS Manual](https://github.com/thesaurus-linguae-aegyptiae/BTS-Manual) - User manual of Berlin Text System written in DITA.
- [DITA Open Toolkit Documentation](https://github.com/dita-ot/docs) - Source code for the DITA-OT documentation.
- [Oxygen XML User Guide](https://github.com/oxygenxml/userguide) - Source code for the Oxygen XML documentation.

DITA has much more elements than Markdown and reStructuredText. If you encounter soemthing unknown, resort to **📘 official specifications**.
DITA has much more elements than Markdown and reStructuredText. If you encounter something unknown, resort to **📘 official specifications**.

- [DITA Version 1.3](https://docs.oasis-open.org/dita/dita/v1.3/) - The latest official specifications for DITA, which was released on Jun 19, 2018.
- [Lightweight DITA: An Introduction Version 1.0](https://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.html) - The Committee Note 02 for Lightweight DITA, which was approved on Oct 30, 2018.

If you like to stay current with DITA developments, visit the **📁 official repositories** in GitHub often.

- [DITA Specification](https://github.com/oasis-tcs/dita) - The official repository for the source files of the DITA specification developed and maintained by the DITA Technical Committee.
- [Leightweight DITA Specification](https://kkgithub.com/oasis-tcs/dita-lwdita) - The official repository for source files of the Lightweight DITA specification developed and maintained by the Lightweight DITA Subcommittee.
- [Lightweight DITA Specification](https://kkgithub.com/oasis-tcs/dita-lwdita) - The official repository for source files of the Lightweight DITA specification developed and maintained by the Lightweight DITA Subcommittee.
- [DITA Specializations](https://github.com/oasis-open/dita-specializations) - The official repository for DITA specializations that were developed by the DITA Technical Committee, but are no longer part of the DITA standard.

### S1000D

S1000D is an international specification for procurement and production of technical publications, which was initially developed for military aerospace industries and spread to various civil and military aeroamphibious equipments later.
S1000D is an international specification for procurement and production of technical publications, which was initially developed for military aerospace industries and spread to various civil and military aero-amphibious equipments later.

S1000D is the most complicated standard for technical documentations. That means, there are rare free resources for self-study.

Here are the **📁 official specifications and implementations in specific industries**.

- [S1000D Specifications](https://users.s1000d.org/Default.aspx) - All versions of official specifications for S1000D.
- [ATA Spec 1000BR: Civil Aviation Business Rules for S1000D](https://publications.airlines.org/CommerceProductDetail.aspx?Product=308) - An implementation of S1000D specification in civil aviation industry, which can not be accessd for free.
- [ATA Spec 1000BR: Civil Aviation Business Rules for S1000D](https://publications.airlines.org/pages/spec1000br-civil-aviation-business-rules-for-s1000d) - An implementation of S1000D specification in civil aviation industry (paid resources).
- [S1000D DIG Business Rules](https://www.gerkemulder.nl/DIG_Business_Rules_issue_1.0_170619.pdf) - An implementation of S1000D specification in the defense industry.
- [The Shipdex Protocol: Issue 2.3](http://www.shipdex.org/shipdex-viewer-free.asp) - An implementation of S1000D specification in the shipping industry.

Expand Down Expand Up @@ -286,30 +286,30 @@ Equipping yourself with some programming skills will enable you to complete some

### Regular expressions

A regular expression (regex) is a pattern that the regex engine can use to find or match substrings. Regexes is extremely useful in finding and replacing texts or strings in text files.
A regular expression (regex) is a pattern that the regex engine can use to find or match substrings. Regex is extremely useful in finding and replacing texts or strings in text files.

If you are completely new to regexes, the following **📙 tutorial** is the best starting point for you:
If you are completely new to regex, the following **📙 tutorial** is the best starting point for you:

- [Regular Expressions: The Complete Tutorial](https://gotellilab.github.io/Bio381/Scripts/Feb07/RegularExpressionsTutorial.pdf) - Easy-to-understand and practical book for regex beginners.

Use an **💻 online tool** to experiment the regexes in the tutorial. It will make your studying easy and interesting.
Use an **💻 online tool** to experiment the regex in the tutorial. It will make your studying easy and interesting.

- [Regex 101](https://regex101.com/) - Online tool to build, test and debug regexes.
- [RegExr](https://regexr.com/) - Online tool to learn, build and test regexes.

> [!TIP]
> You can also use a text editor with support for regexes, such as VS Code.
> You can also use a text editor with support for regex, such as VS Code.
Take a **📔 cheatsheet or quick reference** at hand to check the regex syntax at any time:
Take a **📔 cheat sheet or quick reference** at hand to check the regex syntax at any time:

- [Regular Expression Language: Quick Reference](https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference) - Quick reference for regexes from Microsoft.
- [Regular Expression Syntax Cheat Sheet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet) - Cheat sheet for regexes in the JavaScript Guide from MDN Web Docs.
- [Regular Expression Language: Quick Reference](https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference) - Quick reference for regex from Microsoft.
- [Regular Expression Syntax Cheat Sheet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet) - Cheat sheet for regex in the JavaScript Guide from MDN Web Docs.

### XSL

XSL (Extensible Stylesheet Language) is a styling language for XML. It consists of three parts: XSLT, XPath, and XSL-FO.

**XSLT** (XSL Transformations) is a language for tranforming XML documents. It is widely used in many purposes other than stylesheets, like transforming from one XML language to another, generating HTML pages from XML documents, etc.
**XSLT** (XSL Transformations) is a language for transforming XML documents. It is widely used in many purposes other than stylesheets, like transforming from one XML language to another, generating HTML pages from XML documents, etc.

- [XSLT Tutorial](https://www.w3schools.com/xml/xsl_intro.asp) - For XSLT beginners. It was developed by W3Schools.
- [XSLT Version 2.0: Second Edition](https://www.w3.org/TR/xslt20/) - The latest official specification for XSLT, released on Mar 30, 2021.
Expand All @@ -324,7 +324,7 @@ XSL (Extensible Stylesheet Language) is a styling language for XML. It consists

- [XSL-FO Tutorial](https://w3schools.sinsixx.com/xslfo/default.asp.htm) - For XSL-FO beginners. It was developed by W3Schools.
- [XSL-FO Tutorial](https://www.renderx.com/tutorial.html) - Learn-by-example tutorial for XSL-FO beginners. It provides a series of examples working in [XEP](https://www.renderx.com/tools/xep.html).
- [XSL Version 1.1](https://www.w3.org/TR/xsl/) - The lastest official specification for XSL-FO, released on Dec 05, 2006.
- [XSL Version 1.1](https://www.w3.org/TR/xsl/) - The latest official specification for XSL-FO, released on Dec 05, 2006.

### PowerShell

Expand All @@ -346,7 +346,7 @@ If you like to explore more resources about PowerShell, see [Awesome PowerShell]

## Knowledge sharing

More and more professionals are sharing their invaluable expeirence and professional insights online, and so do technical writers. Let's learn from others!
More and more professionals are sharing their invaluable experience and professional insights online, and so do technical writers. Let's learn from others!

### Blogs

Expand Down

0 comments on commit e75200d

Please sign in to comment.