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/. Each site appears at 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 <site>\docs\. A new page also needs one line in the nav: section of that site's 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 writing contract for all three sites is maintained with the docs project. 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, for example [Ports](reference/ports.md)
Endings	Task pages end with ## Next steps, concept and reference pages with ## Related
Public content	No internal host names, customer or employee names, ticket numbers, source code names or credentials

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
      - Pull Problems: help/troubleshooting/pull.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 environment; no customer names, internal host names, user names or passwords may be visible.
2. Save it as PNG at the planned path under <site>\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 the site's 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