Contributing to These Docs

For Infolytik staff: how the documentation repository works, how to preview and publish a change, and the conventions every page follows.

How it works

The three MetaMiner documentation sites (SAP BusinessObjects, Tableau, Microsoft Fabric and Power BI) live in one private Git repository, infolytik-docs, on the master branch. Each site is a folder with a mkdocs.yml and a docs\ folder of Markdown pages. A push to master triggers the CI build, which builds all three sites with MkDocs and the Material theme and publishes them to www.infolytik.com/docs/<site>/, live about 12 minutes later.

Folder	Live URL
metaminer-sapbusinessobjects\	https://www.infolytik.com/docs/metaminer-sapbusinessobjects/
metaminer-tableau\	https://www.infolytik.com/docs/metaminer-tableau/
metaminer-microsoft-fabric-powerbi\	https://www.infolytik.com/docs/metaminer-microsoft-fabric-powerbi/

flowchart LR
  E[Edit .md locally] --> P[Preview at 127.0.0.1:8000]
  P --> G[git push to master]
  G --> C[CI builds all sites]
  C --> W[www.infolytik.com/docs]

Before you begin

• Git for Windows and Python 3.11 or newer on PATH (use python, not python3).
• Write access to the infolytik-docs repository. Ask the documentation owner.
• The setup recipe: recipe.txt in the repository root. It is the step-by-step reference for everything below.

Steps

1. Clone the repository to %USERPROFILE%\IdeaProjects\infolytik-docs and check out master.
2. Install the preview tool once: copy local-preview\serve.py and local-preview\serve.cmd to C:\tools\mkdocs\. The first run creates its own Python environment with the exact MkDocs and Material versions the CI build uses.
3. Run C:\tools\mkdocs\serve.cmd and open http://127.0.0.1:8000/. This site appears at /docs/metaminer-microsoft-fabric-powerbi/, the same path as on the website. Pages rebuild a few seconds after you save; a broken build prints the error and keeps the last good version.
4. Edit or add pages under metaminer-microsoft-fabric-powerbi\docs\. A new page also needs one line in the nav: section of metaminer-microsoft-fabric-powerbi\mkdocs.yml; without it the page publishes but does not appear in the menu.
5. Check the page in the browser, including links and the right-hand "On this page" list.
6. Publish:

   git pull
   git add <the files you changed>
   git commit -m "<ticket> - <what changed>"
   git push origin master
   

7. After about 12 minutes, open the live page and refresh. A failed CI build publishes nothing; read its log.

Page conventions

The rules you meet most often:

Rule	Detail
Title	Exactly one # H1, identical to the page's label in nav:, followed by a one-sentence summary
Headings	Only ## and ### below the H1; never ####
Voice	Second person, present tense, imperative steps; no marketing adjectives; no emoji
Links	Relative links to .md files of this site, for example [Ports and Endpoints](reference/ports-endpoints.md); never to the other product sites
Endings	Task pages end with ## Next steps, concept and reference pages with ## Related
Product terms	MetaMiner Server (MMS), MetaMiner Client (MMC), MetaMiner Administrator (MMA), MetaMiner Database (MMDB); Microsoft Fabric, Power BI, Microsoft Entra ID
Public content	No internal host names, customer or employee names, ticket numbers, source code names, credentials, tenant IDs or secrets

Navigation depth

The menu has at most three levels: tab > section > page. Top-level entries render as tabs, second-level entries as bold section headings in the sidebar, third-level entries as pages. A section may start with an index.md (listed without a label). Do not nest deeper; split a section instead.

mkdocs.yml (excerpt)

nav:
  - Help:                          # tab
    - help/index.md                # section landing page
    - Troubleshooting:             # section
      - Collection Problems: help/troubleshooting/collection.md   # page

Screenshot placeholders

Pages mark each spot that needs a screenshot with a screenshot admonition. The title says what the image must show; the body is the planned image path, relative to the page.

!!! screenshot "Image of the MMA Create Log Bundle dialog"
    `../images/help/mma-create-log-bundle.png`

To replace a placeholder:

1. Take the screenshot exactly as the title describes. Use a test tenant; no customer names, real user names, tenant IDs, internal host names or secrets may be visible.
2. Save it as PNG at the planned path under metaminer-microsoft-fabric-powerbi\docs\images\ (kebab-case file name).
3. Replace the whole admonition with an image link that keeps the description as alt text:

   ![MMA Create Log Bundle dialog](../images/help/mma-create-log-bundle.png)
   

4. Preview the page and check that the image loads.

TODO admonitions

A todo admonition marks a fact that is not yet verified or needs a decision. Each one names what is missing and where to check. Remove it when you resolve it, and update the ## Chapter status list on the section's index.md.

!!! todo "TODO: confirm the default value of this setting"
    Source to check: the product code or the release notes.

Never replace a TODO with a guess. If you cannot verify a fact, leave the TODO in place.

Verify

• The page appears in the menu at the intended place.
• The local preview shows no build warnings for your page.
• Links open the intended pages, and images load.

Troubleshooting

The page is missing from the menu

Its line is missing from nav: in mkdocs.yml, or the path in that line is wrong. Paths use forward slashes.

Port 8000 is busy

Run C:\tools\mkdocs\serve.cmd --port 8001.

The local preview looks different from the live site

Run git pull. The live site is whatever is on master.

Next steps

• Help
• Glossary