Skip to content

Commit

Permalink
Merge pull request #23 from alps-asd/proofreading-rector
Browse files Browse the repository at this point in the history 
トップページを校正
  • Loading branch information
@koriym
koriym committed Feb 10, 2024
2 parents 6e735ca + d7e5c67 commit 3f96ed6
Show file tree
Hide file tree
Showing 6 changed files with 141 additions and 110 deletions.
3 changes: 3 additions & 0 deletions _includes/manuals/1.0/en/contents.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@
<li class="nav-item">
<a class="nav-link {% if page.permalink == '/manuals/1.0/en/link.html' %}active{% endif %}" href="/manuals/1.0/en/link.html">Resource</a>
</li>
<li class="nav-item">
<a class="nav-link {% if page.permalink == '/manuals/1.0/en/faq.html' %}active{% endif %}" href="/manuals/1.0/en/faq.html">FAQ</a>
</li>
</ul>
</div>
</nav>
3 changes: 3 additions & 0 deletions _includes/manuals/1.0/ja/contents.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@
<li class="nav-item">
<a class="nav-link {% if page.permalink == '/manuals/1.0/ja/link.html' %}active{% endif %}" href="/manuals/1.0/ja/link.html">リソース</a>
</li>
<li class="nav-item">
<a class="nav-link {% if page.permalink == '/manuals/1.0/ja/faq.html' %}active{% endif %}" href="/manuals/1.0/ja/faq.html">FAQ</a>
</li>

</ul>
</div>
Expand Down
60 changes: 60 additions & 0 deletions manuals/1.0/en/faq.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
layout: docs-en
title: FAQ
category: Manual
permalink: /manuals/1.0/en/faq.html
---
# FAQ

<strong>Q. Who can use the software</strong>?

A. It can be used by anyone involved in site creation (engineers, designers, POs).

<strong>Q. What kind of people can write ALPS</strong>?

A. Anyone who can understand XML and JSON and can do simple HTML coding can write ALPS.

<strong>Q. How do you use it?</strong>

A. It is used to design a site by organizing information into the minimum necessary elements, and to design web and API services. The design can be expressed in formats such as JSON and XML, and documents such as transition diagrams and vocabulary lists can be generated. In addition, each producer can know the exact words, meanings and structures of information based on the information design.

<strong>Q. What is information design</strong>?

A. Based on IA (Information Architecture), it defines the information (meta-information) of information in terms of ontology (meaning of words), taxonomy (classification of information), and choreography (links).

<strong>Q. Is it used for design clarification</strong>?

A. No, it is not. It can be used as a modeling tool from the very early stage of site design to organize information and formulate what kind of site it will be.

<strong>Q. What do I need to write ALPS</strong>?

A. You need an editor to edit JSON and XML.

<strong>Q. Isn't it hard to edit XML and JSON directly</strong>?

A. If you use an editor that supports schemas such as WebStorm, you can edit them comfortably with completion and validation.

<strong>Q. Which is better, XML or JSON</strong>?

A. There is no difference in functionality. There is also no need to unify them when using multiple ALPS files. Please compare them in practice. [XML](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.xml) / [JSON](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.xml) [JSON](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.json)

<strong>Q. Can it be used for APIs without links</strong>?

A. Yes. It cannot represent a transition diagram, but it can generate a vocabulary and documentation of the nature of the information.

<strong>Q. Are there any other technologies that are similar to ALPS?</strong>

A. There are no direct competitors. A similar technology is [Microformat](http://www.asahi-net.or.jp/~ax2s-kmtn/internet/rec-owl-features-20040210.html).

<strong>Q. What is the difference from IDL such as OpenAPI</strong>?

A. ALPS deals with REST abstractions that are higher than HTTP. Therefore, it can be used as a modeling and design language for OpenAPI implementations.

<strong>Q. Do I need it</strong>?

A. If you want to model information to improve the quality of user experience, or if you want a reference (SSOT) to unify the understanding among production members, or if you want to overview and reuse your design, or if you want to keep your information design as a standardized document, ALPS+ASD will be useful as your information design modeling tool or as a format to express it.

---

*[This manual]((https://github.com/alps-asd/alps-asd.github.io)) has been machine translated by [DeepL](www.DeepL.com/Translator)*. *Help us improve the quality of our translations!*

68 changes: 10 additions & 58 deletions manuals/1.0/en/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,70 +8,22 @@ permalink: /manuals/1.0/en/

![ASD](https://alps-asd.github.io/app-state-diagram/blog/profile.svg)

## What is ALPS?
## ALPS: A format for clarifying application-level semantics and structure

Application-Level Profile Semantics (ALPS) is a format for expressing application-level semantics (the meaning and structure of words and phrases). It is useful for explaining information and understanding operations.
Application-Level Profile Semantics (ALPS) is a format that expresses application-level semantics and adds application-specific information to general-purpose media such as JSON and HTML. operations, making the development process more efficient, improving compatibility between systems, and facilitating API reusability and discoverability.

## What is ASD?
Consider the example of an e-commerce platform. When integrating with multiple payment services, ALPS standardizes the meaning of data and operations for each step of the payment process, facilitating API integration across different systems. Front-end and back-end developers can also communicate effectively in a common language to quickly add and improve functionality.

ASD (Application State Diagram) is the name of the application state transition diagram generated from ALPS documents and the [documentation generation tool](https://github.com/alps-asd/app-state-diagram).
## ASD: Visualization of Application State Transitions

ASD (Application State Diagram) is a tool for visualizing application state transitions and actions from ALPS documents. This enables a bird's-eye view of the overall structure of the application and an intuitive grasp of the transitions between states and possible actions. For example, in an online shopping application, the process from the user's search for a product to its purchase can be clearly visualized, making it easier for developers to understand the choices and possible actions the user faces at each stage. This aids design decisions that lead to improved user experience.

## Uses
The use of ASDs provides a common point of reference (Single Source of Truth, [SSOT](https://en.wikipedia.org/wiki/Single_source_of_truth)) for nearly all team members involved in a project, including product owners, back-end and front-end developers, and UI/UX designers. . This facilitates effective communication and cooperation among team members with different areas of expertise, helping to bring complex projects and new members on board quickly. It also allows the application flow and logic to be quickly evaluated and adjusted accordingly, providing an opportunity to identify and resolve problems early in the design process, directly contributing to increased development efficiency and improved application quality.

You can design a REST application from a pure information design perspective, excluding UI/UX, and get a bird's eye view of the whole system. Also, the defined vocabularies and links can be used as SSOT(Single source of truth) for shared understanding.
Utilizing ASD increases project transparency and minimizes discrepancies between the visions held by each team member.

## FAQ
## Information Architecture for REST Application Design

<strong>Q. Who can use the software</strong>?

A. It can be used by anyone involved in site creation (engineers, designers, POs).

<strong>Q. What kind of people can write ALPS</strong>?

A. Anyone who can understand XML and JSON and can do simple HTML coding can write ALPS.

<strong>Q. How do you use it?</strong>

A. It is used to design a site by organizing information into the minimum necessary elements, and to design web and API services. The design can be expressed in formats such as JSON and XML, and documents such as transition diagrams and vocabulary lists can be generated. In addition, each producer can know the exact words, meanings and structures of information based on the information design.

<strong>Q. What is information design</strong>?

A. Based on IA (Information Architecture), it defines the information (meta-information) of information in terms of ontology (meaning of words), taxonomy (classification of information), and choreography (links).

<strong>Q. Is it used for design clarification</strong>?

A. No, it is not. It can be used as a modeling tool from the very early stage of site design to organize information and formulate what kind of site it will be.

<strong>Q. What do I need to write ALPS</strong>?

A. You need an editor to edit JSON and XML.

<strong>Q. Isn't it hard to edit XML and JSON directly</strong>?

A. If you use an editor that supports schemas such as WebStorm, you can edit them comfortably with completion and validation.

<strong>Q. Which is better, XML or JSON</strong>?

A. There is no difference in functionality. There is also no need to unify them when using multiple ALPS files. Please compare them in practice. [XML](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.xml) / [JSON](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.xml) [JSON](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.json)

<strong>Q. Can it be used for APIs without links</strong>?

A. Yes. It cannot represent a transition diagram, but it can generate a vocabulary and documentation of the nature of the information.

<strong>Q. Are there any other technologies that are similar to ALPS?</strong>

A. There are no direct competitors. A similar technology is [Microformat](http://www.asahi-net.or.jp/~ax2s-kmtn/internet/rec-owl-features-20040210.html).

<strong>Q. What is the difference from IDL such as OpenAPI</strong>?

A. ALPS deals with REST abstractions that are higher than HTTP. Therefore, it can be used as a modeling and design language for OpenAPI implementations.

<strong>Q. Do I need it</strong>?

A. If you want to model information to improve the quality of user experience, or if you want a reference (SSOT) to unify the understanding among production members, or if you want to overview and reuse your design, or if you want to keep your information design as a standardized document, ALPS+ASD will be useful as your information design modeling tool or as a format to express it.

---

*[This manual]((https://github.com/alps-asd/alps-asd.github.io)) has been machine translated by [DeepL](www.DeepL.com/Translator)*. *Help us improve the quality of our translations!*
ALPS and ASD are important tools for designing and understanding REST applications within the framework of information architecture. ALPS standardizes the meaning and structure of the data handled by the application and uses a common vocabulary to define the meaning and function of information. ASD, on the other hand, provides a state transition diagram of the application, helping to visually understand the user's actions and the application's reactions. Thus, ALPS and ASD provide a foundation for enhancing information architecture in REST application development, supporting efficient communication among teams, and improving consistency and quality throughout the project.

Building a **basis of shared understanding** that resolves conflicts among diverse developers is essential to increase development efficiency, provide a superior user experience, and ensure project sustainability. ALPS and ASD can be very effective tools to achieve this goal.
55 changes: 55 additions & 0 deletions manuals/1.0/ja/faq.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
layout: docs-ja
title: FAQ
category: Manual
permalink: /manuals/1.0/ja/faq.html
---
# FAQ

<strong>Q. どのような人が利用できますか</strong>

A. サイト制作に関わる全ての人（エンジニア、デザイナー、PO）が利用することができます。

<strong>Q. どのような人がALPSを記述できますか</strong>

A. XMLやJSONを理解でき、簡単なHTMLのコーディングができる人ならALPSを記述することができます。

<strong>Q. どのように使いますか</strong>

A. 情報を最小限必要な要素に整理してサイト設計を行い、WebやAPIサービスの設計に使います。設計はJSONやXMLなどのフォーマットとして表し、遷移図やボキャブラリリストなどのドキュメントを生成することができます。また各制作者はその情報設計に基づいて情報の正確な言葉や意味、構造を知ることができます。

<strong>Q. 情報設計とはなんですか</strong>

A. IA（Information Architecture)に基づいて、情報のオントロジー（言葉の意味）、タクソノミー（情報の分類）、コレオグラフィー（リンク）の観点で情報の情報（メタ情報）を定義します。

<strong>Q. 設計の清書に使うものでしょうか</strong>

A. いいえ。サイト設計のごく初期段階から、情報を整理しどのようなサイトを形作っていくなどモデリングツールとして利用できます。

<strong>Q. ALPSを記述するのには何が必要ですか</strong>

A. JSONやXMLを編集するエディターが必要です。

<strong>Q. XMLやJSONを直接編集するのは大変じゃないですか</strong>

A. WebStormなどのスキーマをサポートするエディターを使うと補完やバリデーションが効いて快適に編集できます。

<strong>Q. XMLとJSONではどちらが良いですか</strong>

A. 機能に違いはありません。また複数のALPSファイルを利用する場合でも統一する必要がありません。実際に見比べてみてください。[XML](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.xml) / [JSON](https://github.com/koriym/app-state-diagram/blob/master/docs/blog/profile.json)

<strong>Q. リンクのないAPIにも使えますか</strong>

A. 遷移図は表せませんが、ボキャブラリや情報の性質を表すドキュメントが生成できます。

<strong>Q. ALPSと同様の技術は他にありますか</strong>

A. 直接の競合技術はありません。近い技術に[Microformat](http://www.asahi-net.or.jp/~ax2s-kmtn/internet/rec-owl-features-20040210.html)があります。

<strong>Q. OpenAPIなどのIDLと何が違いますか</strong>

A. ALPSはHTTPよりさらに上位のRESTの抽象を扱います。そのためOpenAPI実装のためのモデリングや設計言語として用いることもできます。

<strong>Q. 私に必要ですか</strong>

A. ユーザー体験の質の向上のために情報中心でサイトを設計したい、制作メンバー間の認識を統一するためのリファレンス（SSOT)が欲しい、設計を俯瞰し再利用したい、情報設計を規格化されたドキュメントとして残したい、などの動機があれば役に立つでしょう。
Loading

0 comments on commit 3f96ed6

Please sign in to comment.