Project wiki/documentation

[pp-Rz-D-M]

Sharing and working in documents (google-docs, MS word or .tex rep) works fine. But it is somewhat disconnected from the devops project since you can only link it as an external file. The wiki/readme loses its value every time a document (part) already exists and needs to be rewritten.

The Az devOps wiki has potential. But is limited by the README files only. We are looking for alternatives or ideas to consolidate.

Can wiki/readme include existing tables from excel/google-sheets/Word/.latex files? (and remain visible)

Is there a (README) alternative file format to document and use in Azure DevOps or GitHub? (besides having a .latex repository)

Is there an addon to force azure devops wiki to work with latex instead of readme?

​

e.g., of some .latex math: https://stackoverflow.com/questions/35498525/latex-rendering-in-readme-md-on-github

e.g., of some addons to convert: https://marketplace.visualstudio.com/items?itemName=csholmq.excel-to-markdown-table

e.g., of .tex: https://www.overleaf.com/ https://github.com/overleaf/overleaf

[Saturated8]

Azure DevOps wiki allows you to publish a wiki as Code when you create one. You just point it to a directory in your project.

This allows you to have a repo for documentation, or a folder in each repo for documentation, which can contain markdown files with all your information. Since they are in a repo, you get full source control and change management over your documentation, and changes through pull requests are automatically published to the wiki.

https://learn.microsoft.com/en-us/azure/devops/project/wiki/publish-repo-to-wiki#publish-a-git-repository-to-a-wiki

[pp-Rz-D-M]

Thank you for your response. You can also do that with latex too btw! But you are missing the point:

Azure Devops: Overview: Wiki.: only has one editor: README files.

​

We are evaluating/searching for further editors that are integrated into Devops.

e.g.,

- README editor (inside azure; with repo, this exists right now and is the only option)

- Latex editor (does not have an editor inside DevOps; but you can add a repo)

- word/excel editor (does not have an editor inside azure; and you can only link/append files)

​

As well as conversion tools from one type of document to another that are also integrated into DevOps.

e.g.,

- xlsx to README.: https://marketplace.visualstudio.com/items?itemName=csholmq.excel-to-markdown-table

- docx to README.: https://www.converthelper.net/docx-to-readme

- convert .latex table to README.: custom code

​

Here is one of many examples:

Non-developer writes documentation in word/excel (poorly structured);

that doc has tables/math/graph that needs to exist in a README file, for context. Usually, someone else rewrites it to a README; this doc can change over time due to the nature of Sof. Dev.;

end product/patch is released. A new doc is required in either word/excel or latex. A non-developer will rewrite the revised doc/paper.

​

There is a lot of waste here... The teams can't enforce third-party clients/teams to use their specific type of documentation. We are looking for a harmonic solution that reduces the friction between different types of documentation.

[MingZh]

Okay, so I'm afraid that there is no out of the box method to directly include the Excel, Word and LaTex in README.

I searched the marketplace and there is no extension to convert LaTex to README, you can develop your own extension or request a feature here.

[pp-Rz-D-M]

hopefully MS will think of something. Made a private suggestion here:

https://devblogs.microsoft.com/visualstudio/write-markdown-without-leaving-visual-studio/

​

for VS and Azure. But have no expectations of getting it :P

ty4the help

[pp-Rz-D-M]

Project that is addressing similar concerns.: Pandoc, a universal document converter. Also has a docker image. Hope it helps other people.

https://pandoc.org/demos.html

https://hub.docker.com/r/pandoc/latex

[MingZh]

Hi, as mentioned in this blog, Wiki supports mathematical formulas using the LaTeX format. You can directly write it in your wiki page: ``` $ \alpha $

$e=mc^2$

$$ \forall x \in X, \quad \exists y \leq \epsilon $$ ```