Skip to content

Enhance Android SDK docs - #1097

Open
NikolaRusakov wants to merge 1 commit into
tolgee:mainfrom
NikolaRusakov:nb/improve-android-sdk-docs
Open

Enhance Android SDK docs#1097
NikolaRusakov wants to merge 1 commit into
tolgee:mainfrom
NikolaRusakov:nb/improve-android-sdk-docs

Conversation

@NikolaRusakov

Copy link
Copy Markdown

Content

  1. introduces Mermeid.js plugin to Docusaurus in order to render visual diagrams
  2. adds key details and missing instructions in introduction section
  3. restructures Android SDK page hierarchy to make it flow better (WIP)
  4. Copy pastes Starter sections from Integrate page from Tolgee Platform
    Demonstrates flow of Documentation-first versus Starter-first principles

@netlify

netlify Bot commented Apr 13, 2026

Copy link
Copy Markdown

Deploy Preview for tolgee-docs ready!

Name Link
🔨 Latest commit 11a29ab
🔍 Latest deploy log https://app.netlify.com/projects/tolgee-docs/deploys/69dd0f1fb7c0fa000811dd89
😎 Deploy Preview https://deploy-preview-1097--tolgee-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@Barush

Barush commented Sep 2, 2026

Copy link
Copy Markdown
Member

I started the review, but this would probably better need a full rework, so I am rather sharing the goals how a docs page should look like when we consider it done:

A finished page has all of these. Think of it as the definition of done, so we can build on this later.

  1. Frontmatter with id, title, description (under 155 characters, written like a search result snippet) and image.
  2. A tl;dr paragraph directly under the H1. Plain prose, 40 to 80 words, no bullets, no links.
  3. A clear path for the reader. If there are two ways to do something (for example JSON format vs strings.xml), the page says so up front and tells the reader how to pick. Then each path is a complete sequence of steps.
  4. Steps in the order the reader will actually do them. Every step has the code the reader pastes and one sentence on what it does. If a step can be verified, the check sits right after that step.
  5. Full, copy paste ready code blocks. We use readable placeholders like your-cdn-url-prefix and your-api-key.
  6. Every link works and points to the page it names. Internal links use the docs route (/android-sdk/usage), not the file (./usage.mdx). No raw URLs pasted as text.
  7. Zero TODO, WIP, FIXME or commented out notes in the page.
  8. No duplicated content. One topic lives on one page. Other pages link to it. If you are pasting the same block on a second page, stop and restructure instead.
  9. Headings that read as the question the reader has (only when this makes sense).
  10. A short "Next steps" section at the end with two or three links.

The tl;dr paragraph below the h1 should answer these questions:

  • Who is this for.
  • What is the feature or the SDK.
  • How do you use it, in one sentence.
  • What benefit does it bring.

A quick test is trying to do the actual thing with the docs as a tutorial. It should always be understandable and doable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants