Mocco

헬프 센터 게시하기

헬프 센터는 제품의 도움말 글을 담은 공개 사이트입니다. 글은 Mocco에서 리치 텍스트 편집기나 Markdown으로 쓰고, 준비되면 게시합니다. 독자는 브라우저에서, 또는 앱 안의 링크로 사이트를 엽니다.

1. 헬프 센터 켜기

워크스페이스 멤버가 워크스페이스의 Products 페이지에서 Help center를 켭니다. 그러면 각 프로젝트에 Help center 페이지가 나타납니다.

2. 사이트 설정하기

프로젝트의 Help center 페이지에서 다음을 고릅니다.

  • Address: 웹 주소에서 사이트를 나타내는 이름입니다. 예를 들어 showyourtime.help.mocco.club의 showyourtime입니다. Mocco 전체에서 고유해야 합니다.

  • Written in: 글을 쓰는 언어입니다.

  • Also offered in: 제공할 계획인 언어입니다. 글이 번역되기 전에는 다른 언어를 고른 독자도 글을 쓴 언어로 보게 됩니다.

그런 다음 Set up help center를 선택합니다.

헬프 센터 설정: 주소, 글을 쓰는 언어, 제공하는 다른 언어

3. 글 구성하고 추가하기

헬프 센터는 컬렉션(최상위, 예: "Getting started")으로 이루어지고, 컬렉션은 섹션(예: "Basics")을, 섹션은 글을 담습니다. 컬렉션은 페이지 맨 아래에, 섹션은 컬렉션 안에, 글은 섹션 안에 추가합니다. 새 글은 편집기에서 열립니다.

페이지에는 모든 글이 상태와 함께 표시됩니다. Draft는 한 번도 게시한 적이 없는 글이고, Published는 사이트에 올라간 글이며, Unpublished changes는 저장한 것보다 이전 버전이 사이트에 보이고 있다는 뜻입니다. 사이트 주소는 맨 위에 있으며, 선택하면 사이트가 열립니다.

Help center 페이지: 섹션 하나와 게시된 글 두 개가 있는 컬렉션, 그리고 사이트 주소

Mintlify에서 가져오기

도움말 사이트가 Mintlify에 있다면 다시 쓰지 말고 가져오세요. Help center 페이지의 Import from Mintlify 아래에서 docs 폴더(docs.json이 있는 폴더)를 고르고, 바로 공개하려면 Publish the imported articles를 켜 둔 채로 Import를 선택합니다.

  • docs.json의 탭, 그룹, 페이지가 같은 순서로 컬렉션, 섹션, 글이 됩니다.

  • Mintlify의 컴포넌트는 일반 Markdown이 됩니다. 단계는 번호 목록, 팁과 노트는 인용 노트, 업데이트 항목은 제목이 됩니다.

  • 페이지가 쓰는 이미지는 Mocco에 업로드됩니다.

  • 각 페이지의 이전 주소(예: /features/widget-features)는 해당 글로 리디렉션되므로, 주소가 Mocco를 가리키게 되면 이전 사이트로 가는 링크도 계속 동작합니다.

  • 다시 가져오면 같은 글이 업데이트되고, 텍스트가 바뀐 글만 바뀝니다.

가져오기가 끝나면 Mocco는 가져오지 못한 항목을 나열합니다. 폴더에 없는 이미지와, docs.json의 내비게이션에 없는 페이지입니다.

같은 폴더를 다시 가져온 결과: 모든 글이 변경되지 않았고, 이미지는 이미 저장되어 있으며, 내비게이션에 없는 페이지가 표시됩니다

4. 쓰고 게시하기

편집기는 Rich text로 열립니다. 독자가 보게 될 모습 그대로 글을 씁니다. 빈 줄에서 /를 입력하면 제목, 목록, 인용, 코드, 구분선, 이미지, 표를 넣을 수 있습니다. 텍스트를 선택하면 굵게, 기울임, 취소선, 코드, 링크로 만들거나 그 줄을 제목으로 바꿀 수 있습니다. 블록 왼쪽의 핸들은 블록을 옮기고, **+**는 아래에 블록을 추가합니다.

리치 텍스트 편집기에서 /를 입력한 모습: Image 항목은 그림을 업로드합니다

제목을 선택하면 나오는 버블 메뉴: 제목 수준, 굵게, 기울임, 취소선, 코드, 링크

편집기가 제공하는 모든 것은 Markdown으로 저장되므로, 글은 사이트, 번역, 앱에서 똑같이 보입니다. 이 때문에 밑줄, 색상, 텍스트 정렬은 없습니다.

Markdown은 왼쪽에 텍스트 자체를, 오른쪽에 독자가 보게 될 글을 보여 주며, 입력하는 대로 갱신됩니다. 원시 HTML처럼 리치 편집기가 보여 주지 못하는 것에 쓰세요. 두 모드를 오가는 것만으로는 아무것도 바뀌지 않고, 수정해야 저장됩니다. 제목(##), 번호 목록과 글머리 목록, 굵게, 링크, 노트(>로 시작하는 줄), 표를 쓸 수 있습니다. 링크는 웹 페이지(https://…), 이메일 주소(mailto:…), 사이트의 다른 페이지(/en/articles/…)로 연결할 수 있습니다. 이미지는 https:// 주소이거나 아래 방법으로 추가한 이미지여야 합니다.

초안은 입력을 멈추고 몇 초 뒤에 저절로 저장됩니다. 제목 옆에 **Saving…**이 보이다가 All changes saved가 표시됩니다. 저장에 실패하면 Try again과 함께 Couldn't save가 표시되고, 텍스트는 편집기에 남아 있습니다. 저장은 사이트에 영향을 주지 않습니다.

  • Publish는 저장하지 않은 내용을 저장하고 초안을 사이트에 올립니다.

  • Unpublish는 글을 사이트에서 내립니다. 텍스트와 기록은 남습니다.

  • Delete article은 확인한 뒤 글과 그 기록을 삭제합니다.

글 편집: 왼쪽은 Markdown, 오른쪽은 미리보기, 제목 옆에는 All changes saved

편집기 아래의 History에는 편집 세션마다 항목이 하나씩 남습니다. 10분 안에 저장한 내용은 같은 항목에 들어가고, 게시하거나 복원하면 새 항목이 시작됩니다. Restore는 이전 버전을 새 항목으로 다시 초안으로 만들므로, 기록에서 사라지는 것은 없습니다. 사이트에 되돌리려면 게시하세요.

이미지 추가하기

스크린샷을 텍스트에 붙여 넣거나, 이미지 파일을 끌어다 놓거나, Add image로 파일을 고르거나, / 메뉴에서 Image를 선택합니다. 이미지는 업로드되어 커서가 있는 곳에 들어갑니다. Markdown에서는 ![name](address) 형태로 들어가고 미리보기에 바로 표시됩니다. 최대 10 MB의 PNG, JPEG, WebP, GIF 이미지를 추가할 수 있으며, 그 밖의 파일은 이유를 알려 주는 메시지와 함께 거부됩니다. 이미지는 업로드하면 게시된 사이트처럼 공개되므로, 공개하고 싶지 않은 내용은 붙여 넣지 마세요.

글에 스크린샷 붙여 넣기: 텍스트에는 이미지의 Markdown이, 미리보기에는 이미지가 보입니다

번역

게시하면 Mocco는 사이트가 제공하는 각 언어로 글을 번역합니다. Mocco에서 자동 번역을 켜 두었을 때의 이야기이고, 켜지 않았다면 언어별로 직접 씁니다. 글의 Translations 섹션에는 모든 언어와 각 언어의 상태가 표시됩니다.

  • Machine translated: 게시된 글로 만든 Mocco의 번역입니다.

  • Reviewed: 사람이 쓰거나 고친 번역입니다. Mocco는 이를 스스로 교체하지 않습니다.

  • Source changed: 이 번역이 만들어진 뒤 글이 다시 게시되었습니다. 검수해서 최신으로 맞추세요.

  • Machine draft ready: 원문이 바뀐 검수 완료 언어에 대해 Mocco가 새 원문에 맞는 버전을 초안으로 만들어 두었습니다. 기존 문장은 유지하고 바뀐 문장만 기계로 번역합니다. 초안을 수락하기 전까지 독자에게는 검수된 텍스트가 계속 보입니다.

  • Failed: 번역이 글의 구조(제목, 코드 블록, 링크)를 바꿔서 Mocco가 사용하지 않았습니다. 이유가 표시됩니다.

  • Not translated: 아직 아무것도 없습니다. 그 언어의 독자는 글을 쓴 언어로 보게 됩니다.

글의 번역: 영어는 검수 완료, 일본어는 아직 번역되지 않음

번역 검수하기

언어에서 Review(또는 Edit)를 선택합니다. 왼쪽에는 직접 쓴 글이, 오른쪽에는 번역이 나오며, 오른쪽은 Markdown과 Preview로 전환할 수 있습니다. 맨 윗줄에는 그 언어를 마지막으로 검수한 사람과 시각이 표시됩니다.

번역이 만들어진 뒤 원문이 바뀌었다면, 검수 화면은 바뀐 내용부터 보여 줍니다. 바뀌거나 추가되거나 삭제된 문단, 제목, 표 셀마다 이전 텍스트에 취소선이 그어져 새 텍스트 위에 표시됩니다. 바뀌지 않은 부분은 개수만 세어 주므로, 무엇을 봐야 하는지 정확히 알 수 있습니다.

오래된 영어 번역 검수: 원문에서 바뀐 두 문장과 Accept draft, Edit draft가 있는 기계 초안

기계 초안이 준비되어 있다면 Accept draft는 초안을 그대로 검수된 텍스트로 만듭니다. Edit draft는 초안을 편집기에 열어 먼저 고칠 수 있게 합니다.

검수 편집기: 원문 글 옆에 영어 번역의 미리보기가 있고 Save as reviewed 버튼이 있습니다

Save as reviewed는 내 텍스트를 유지하고 그 언어를 검수 완료로 표시합니다. 기계 번역이 이미 맞다면 버튼은 Mark reviewed로 바뀌며, 바꾸지 않고 저장하면 검수 완료로 표시됩니다. Mocco는 검수된 텍스트를 스스로 교체하지 않으며, 모든 검수는 누가 했는지와 함께 워크스페이스의 감사 로그에 기록됩니다.

Translate again은 기계 번역을 새로 요청합니다. 검수된 언어에서는 기계의 텍스트가 사이트에서 내 텍스트를 대체하므로 먼저 확인을 요청합니다. 내 버전은 글의 기록에 남습니다.

헬프 센터를 git으로 관리한다면 번역도 git에 둘 수 있으며, 이 경우 콘솔에서는 읽기 전용으로 표시됩니다. 헬프 센터를 git으로 관리하기를 참고하세요.

모든 번역을 한눈에 보기

사이트가 다른 언어를 제공하면 Help center 페이지에 Translations 링크가 생깁니다. 맨 위에는 언어마다 게시된 글 중 검수 완료, 기계 번역, 원문보다 오래됨(Source changed), 실패, 번역 대기 중, 아직 번역되지 않은 글이 각각 몇 개인지 표시됩니다.

Translations 페이지: 영어와 일본어의 개수, 그리고 각 언어의 상태가 있는 글 그리드

그 아래에는 게시된 모든 글이 언어별 상태와 함께 나열됩니다. Needs attention을 선택하면 오래되었거나 실패했거나 번역되지 않은 언어가 있는 글만, Source changed나 Failed를 선택하면 해당 글만 나열됩니다. 언어를 고르면 그 언어의 열만 보입니다. 각 상태를 선택하면 글 안에서 그 언어의 검수가 열리므로, 목록을 따라 내려가며 하나씩 최신으로 맞출 수 있습니다.

일본어의 Needs attention: 일본어 번역이 오래되었거나 실패했거나 없는 글들

페이지 주소에 필터와 언어가 유지되므로, 그 보기를 북마크하거나 팀원에게 보낼 수 있습니다.

언어를 고른 독자는 그 언어의 번역을 보며, 글 목록에는 컬렉션과 섹션을 포함해 번역된 제목이 표시됩니다.

공개 사이트의 글 영어 번역

아무도 검수하지 않은 기계 번역에는 제목 아래에 독자의 언어로 Automatically translated가 표시됩니다. 직접 번역을 저장하면 이 표시는 사라집니다.

글을 다시 게시하면 이전 버전으로 만든 번역은 업데이트될 때까지 계속 표시되며, 맨 위에 안내가 붙습니다. 번역된 뒤 원문이 바뀌었다는 내용과, 글을 쓴 언어의 글로 가는 링크입니다. 기계 번역은 Mocco가 새 버전을 번역하는 즉시 안내가 사라지고, 검수된 번역은 다시 검수할 때까지 안내가 유지됩니다.

공개 사이트의 일본어 기계 번역: 원문이 바뀌었다는 안내와 영어 글 링크, 제목 아래의 "Automatically translated", 오른쪽 위의 언어 전환기

모든 언어에서 이름과 단어를 같게 유지하기

Help center 페이지에는 Glossary로 가는 링크도 있습니다. 모든 번역이 따르는 단어 목록입니다. 용어를 추가하고 규칙을 고르세요.

  • Keep as written은 제품 이름, 기능 이름, 버튼 레이블에 씁니다. 모든 언어에서 쓴 그대로 유지되며, Mocco는 이를 번역으로 보내지 않습니다.

  • Fixed translation은 항상 같은 방식으로 번역해야 하는 단어에 씁니다. 제공하는 언어마다 번역을 입력하세요. 이를 쓰지 않은 기계 번역은 거부되고 다시 요청되며, 그래도 쓰지 않으면 그 언어는 이전 텍스트를 유지하고 Failed로 표시됩니다.

다음에 용어를 편집할 사람을 위해 이유를 메모로 남깁니다.

Glossary 페이지: "home screen"을 고정된 일본어 번역과 함께 추가하는 모습, 그리고 이미 있는 용어들(하나는 그대로 유지, 둘은 고정 번역)

용어를 추가, 변경, 삭제하면 Mocco는 그 용어가 들어 있는 문장만, 그 용어로 결과가 달라지는 언어에서 다시 번역합니다. 나머지 문장은 그대로입니다. 누군가 검수한 언어는 텍스트를 유지하고, 새 용어가 반영된 기계 초안이 생겨 검수에서 수락하거나 편집할 수 있습니다.

많은 용어를 한 번에 추가하려면 스프레드시트에서 내보낸 파일 같은 CSV 파일을 가져오세요. 첫 행은 열 이름입니다. term, rule(keep 또는 fixed이며, 비워 두면 번역이 있는 행은 fixed), note, 그리고 언어마다 코드로 이름 붙인 열(ja, ko, de, …)이 있습니다. Mocco는 가져오기 전에 읽은 용어 수와 읽지 못한 줄을 보여 줍니다. 이미 용어집에 있는 용어는 대소문자와 상관없이 업데이트되고, 파일에 없는 용어는 그대로 남습니다. Download the glossary as CSV는 현재 용어집을 같은 형식으로 내려받게 해 주므로, 편집해서 다시 가져올 수 있습니다.

CSV 가져오기: 용어 세 개가 준비되었고, fixed 용어에는 번역이 필요해서 5번째 줄이 거부되었습니다

MCP로 연결한 에이전트는 용어집을 읽을 수 있지만, 변경은 콘솔에서만 할 수 있습니다.

자체 도메인 사용하기

헬프 센터는 처음부터 <address>.help.mocco.club에 있습니다. help.example.com 같은 자체 도메인에서 제공하려면 Mocco 팀에 도메인 추가를 요청하고, 알려 주는 대상으로 DNS 레코드(CNAME)를 설정해 Mocco를 가리키게 하세요. 레코드가 확인되면 사이트와 가져온 사이트의 모든 이전 주소가 그 도메인에서 응답합니다. 그러면 Help center 페이지에 도메인 링크가 표시됩니다.

검색 엔진과 AI

헬프 센터는 제공하는 모든 언어로 모든 글의 위치를 검색 엔진에 알립니다. 주소의 /sitemap.xml에서 확인할 수 있습니다(자체 도메인이 있다면 그 도메인에서). Google, Bing, ChatGPT 검색, Claude, Perplexity 같은 검색 엔진과 AI 검색은 이 파일을 항상 읽을 수 있으므로, 질문하는 사람들이 내 답변을 찾게 됩니다.

Slack, Discord, KakaoTalk, X에 공유한 글 링크에는 헬프 센터 이름, 글의 컬렉션, 제목, 첫 문장이 담긴 카드가 표시되며, 글이 바뀌면 새 카드가 만들어집니다.

AI 어시스턴트와 코딩 에이전트도 글을 Markdown으로 읽을 수 있습니다. 헬프 센터 주소의 /llms.txt는 모든 글을 나열하고(다른 언어는 /<language>/llms.txt), 글 주소에 .md를 붙이면 그 글의 텍스트가 나옵니다.

AI 기업은 모델을 학습시키려고 텍스트를 수집하는 크롤러도 보냅니다. 기본적으로 허용되어 있습니다. 막으려면 Help center 페이지 맨 아래의 Allow AI training crawlers를 해제하세요. 그러면 사이트의 /robots.txt가 GPTBot, ClaudeBot, Google-Extended, Applebot-Extended, CCBot, meta-externalagent, Bytespider를 막고, 검색은 계속 동작합니다. 크롤러는 다음 방문 때 robots.txt를 따르며, 이미 수집한 내용이 지워지지는 않습니다.

Allow AI training crawlers가 해제된 Help center 페이지의 Search engines and AI 섹션

5. 독자가 보는 것

사이트는 독자가 고른 언어로 컬렉션과 그 글을 나열하며, 맨 위에 언어 전환기가 있습니다. 글에서 전환기는 번역된 각 언어의 같은 글로 이동하고, 번역이 없으면 그 언어의 홈으로 이동합니다. 각 글에는 고유한 주소 /<language>/articles/<id>-<name>이 있습니다. <id> 부분은 바뀌지 않으므로 글 이름을 바꿔도 링크가 계속 동작합니다. 게시된 변경, 게시 취소되거나 삭제된 글, 새 번역은 글과 사이트 홈에 바로 나타나고, 다른 페이지의 글 목록은 1분 안에 따라잡습니다.

독자는 모든 페이지 맨 위의 상자에서 검색할 수 있습니다. 입력한 모든 단어가 독자가 읽는 언어(아직 번역되지 않은 글은 내가 쓴 언어)의 글 제목이나 본문에 나와야 하며, 제목이 일치하는 글이 먼저 나옵니다. 검색 상자와 결과는 독자의 언어로 표시됩니다.

헬프 센터 검색: 단어에 대한 결과와 각 글의 스니펫

공개 헬프 사이트에 게시된 글: 글 목록과 언어 전환기

모든 글 아래에서 독자는 자기 언어로 **Was this article helpful?**에 Yes 또는 No로 답할 수 있습니다. 같은 날 마음을 바꾸면 첫 답변이 교체되므로, 독자는 하루에 한 번만 집계됩니다.

공개 글의 끝: "Was this article helpful?", Yes가 선택되었고 감사 메시지가 있습니다

Mocco의 글 페이지에는 최근 30일 동안 독자가 답한 내용이 표시됩니다. Yes의 비율, 개수, 앱에서 보낸 최신 의견입니다. 손봐야 할 글을 찾는 데 쓰세요.

Mocco의 글에 있는 Was this helpful? 섹션: 67% 도움됨, yes 4건과 no 2건, 의견 하나

앱에서 글 추천하기

앱에서도 헬프 센터를 검색할 수 있습니다. 예를 들어 사용자가 문의를 쓰는 동안 관련 글을 보여 주면, 보내기 전에 답을 찾을 수도 있습니다. API keys 페이지에서 help:read 스코프가 있는 Publishable 키를 만드세요(이미 Messenger를 쓰는 앱은 그 키에 스코프를 추가할 수 있습니다). 그런 다음 React Native에서 다음과 같이 씁니다.

import { createHelp, useHelpSearch } from '@mocco/react-native/messenger';

const help = createHelp({ publishableKey: 'mk_pub_…' });

function Suggestions({ text }: { text: string }) {
  // Waits until typing pauses; `any` finds articles that share any word with the text.
  const { hits } = useHelpSearch(help, text, { locale: 'en', limit: 3, match: 'any' });
  return hits.map(hit => <ArticleLink key={hit.path} title={hit.title} url={hit.url} />);
}

앱의 새 메시지 화면이 "The widget doesn't open the camera"에 대해 헬프 센터의 "iOS widget" 글을 추천하는 모습

각 결과에는 글의 title, 본문의 snippet, 헬프 사이트의 url이 있으며, 번역된 글이면 url은 독자의 언어로 제공됩니다. 다른 클라이언트는 GET https://api.mocco.club/v1/help/search?q=…&locale=en&match=any를 호출하고, 키를 Authorization: Bearer mk_pub_…로 보내면 됩니다.

앱에서 글 보여 주기

같은 키로 사람들을 브라우저로 보내는 대신 앱 안에서 헬프 센터를 열 수 있습니다. getSite는 컬렉션, 섹션, 글 제목을 나열하고, getArticle은 글 하나의 Markdown을 돌려주므로 아무 Markdown 컴포넌트로나 렌더링할 수 있습니다.

import { createHelp } from '@mocco/js'; // or '@mocco/react-native/messenger'

const help = createHelp({ publishableKey: 'mk_pub_…' });

const site = await help.getSite({ locale: navigator.language });
const article = await help.getArticle(site.collections[0].sections[0].articles[0].id, { locale: 'en' });

기기의 언어는 받은 그대로 넘기세요(en-GB는 영어로 처리됩니다). 그 언어로 아직 번역되지 않은 글은 내 언어로 도착하며, article.locale이 어떤 언어를 받았는지 알려 줍니다. 게시된 글만 있습니다. 초안이나 게시 취소한 글은 null로 응답합니다. 웹에서는 프로젝트 웹 앱의 Web origins에 사이트 주소를 추가해야(워크스페이스와 프로젝트 설정하기) 브라우저가 키로 Mocco를 호출할 수 있습니다.

앱에서도 "Was this helpful?"를 물어볼 수 있으며, 팀만 볼 수 있는 의견을 선택적으로 받을 수 있습니다. 독자가 하루에 한 번만 집계되도록 createHelp에 앱이 설치마다 유지하는 ID를 주세요. Mocco는 그 ID를 뒤섞은 형태로만 저장합니다.

const help = createHelp({ publishableKey: 'mk_pub_…', visitorId: installId });

await help.sendFeedback(article.id, { helpful: false, locale: article.locale, comment: 'Missing Android steps' });