# What recommended tools to publish user manual in GitHub WiKi

**URL:** <https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504>\
**Category:** Tooling\
**Tags:** documenter, github\
**Created:** [May 4, 2021, 8:00am UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504 "2021-05-04T08:00:57Z")\
**Posts on this page:** 13\
**Page:** 1

<div class="post-metadata">

**Author:** ![JosephPollacco](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/josephpollacco/32/51404_2.png) [@JosephPollacco](https://discourse.julialang.org/u/JosephPollacco)\
**Post date:** [May 4, 2021, 8:00am UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/1 "2021-05-04T08:00:57Z")

</div>

I wrote a large scientific package SoilWater-ToolBox [https://github.com/joseph-pollacco/SoilWaterToolbox](https://github.com/joseph-pollacco/SoilWaterToolbox) and now it is time to write the **user’s manual** which we plan to publish in _GitHub_. I am looking for advice on the recommended tools to write a complex manual which will describe the model 😃:

```julia
1. Is GitHub wiki the recommended website to write a manual?

2. Is there a recommended template?

3. How can we write Latex equations?

4. What would be the recommended Markdown editor OpenSource or paid?

```

Many thanks for helping me to get started.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [May 4, 2021, 8:19am UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/2 "2021-05-04T08:19:23Z")

</div>

1. yes

2. a package like Documenter.jl is usually used to generate the files, but there are alternatives

3. [LaTeX Syntax · Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/man/latex/)

4. most editors are fine for Markdown, it is plain text after all. Just use whatever you use for Julia coding.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [May 4, 2021, 7:47pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/3 "2021-05-04T19:47:31Z")

</div>

The advantage of Documenter is that you can “reuse” the docstrings of your functions/types for yhe API part, and use true julia scripts, that you can keep under testing, with Literate.jl for the “tutorials”/'exemple" part of the documentation.

In practice, Literate.jl converts julia scripts (.jl) with markdown embedded as comment to markdown files (.md) with code embedded as example block, and then Documenter transfrorms everything to html and integrates with GitHub Continuous integration to piblish on github pages.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [May 4, 2021, 7:58pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/4 "2021-05-04T19:58:06Z")

</div>

By the way, as you work on soil topics, you may be interested in this conference:

> **[DEEPSURF2022](https://deepsurf-ic.univ-lorraine.fr/)**
>
> International Conference on the role of underground, soils and forest use for energy transition porposes. 18-21 October 2022, Nancy - France.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [May 4, 2021, 8:08pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/5 "2021-05-04T20:08:15Z")

</div>

I had a quick look on the repository. I think before looking at the documentation, you should reorganise the code as a standard Julia package.

You could have a look on my tutorial on how to develope a package: [11 - Developing Julia packages - Julia language: a concise tutorial](https://syl1.gitbook.io/julia-language-a-concise-tutorial/language-core/11-developing-julia-packages)

---

<div class="post-metadata">

**Author:** ![JosephPollacco](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/josephpollacco/32/51404_2.png) [@JosephPollacco](https://discourse.julialang.org/u/JosephPollacco)\
**Post date:** [May 4, 2021, 9:50pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/6 "2021-05-04T21:50:17Z")

</div>

Thanks Antonello Labianco. I could now see the advantages of using _Documenter.jl_ as it can use partly the docstrings of the functions and therefore enables not to duplicate the efforts and to reinforce good programming practice to document the functions.

---

<div class="post-metadata">

**Author:** ![rpmuller](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rpmuller/32/2262_2.png) [@rpmuller](https://discourse.julialang.org/u/rpmuller)\
**Post date:** [May 4, 2021, 9:52pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/7 "2021-05-04T21:52:17Z")

</div>

@sylvaticus Not the OP, but thanks for the tutorial on packages. Answered a few of my lingering questions.

---

<div class="post-metadata">

**Author:** ![JosephPollacco](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/josephpollacco/32/51404_2.png) [@JosephPollacco](https://discourse.julialang.org/u/JosephPollacco)\
**Post date:** [May 4, 2021, 10:02pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/8 "2021-05-04T22:02:37Z")

</div>

**TUTUORIALS/ TEMPLATES / VIDEOS ON USING LITERATE .JL & DOCUMENTER.JL**

I had a quick look at _Literate.jl_  
[https://github.com/fredrikekre/Literate.jl](https://github.com/fredrikekre/Literate.jl)  
& _Documenter.jl_  
[https://juliadocs.github.io/Documenter.jl/stable/](https://juliadocs.github.io/Documenter.jl/stable/)

Which indeed these software are very powerful software. I am wandering if there are some _Tutorials_ or _Videos_ or **simple example** _templates_ which can help beginners to get started quickly?

As the proposed examples are good but may be overhelming for a beginner?  
[Examples](https://juliadocs.github.io/Documenter.jl/stable/man/examples/#Examples)  
[https://juliadocs.github.io/Documenter.jl/stable/man/examples/#Examples](https://juliadocs.github.io/Documenter.jl/stable/man/examples/#Examples)

Thanks for providing to the community such a powerful tool.

---

<div class="post-metadata">

**Author:** ![JosephPollacco](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/josephpollacco/32/51404_2.png) [@JosephPollacco](https://discourse.julialang.org/u/JosephPollacco)\
**Post date:** [May 4, 2021, 10:10pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/9 "2021-05-04T22:10:43Z")

</div>

What is the best Markdown software which is best to use for a beginner and has Latex?

For example in **Extensions in Vscode** there are a multitude of **options** , but I do not think that there are any ones which has dedicated _pulldown menus_ or _options_ which will help beginners get started.

---

<div class="post-metadata">

**Author:** ![JosephPollacco](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/josephpollacco/32/51404_2.png) [@JosephPollacco](https://discourse.julialang.org/u/JosephPollacco)\
**Post date:** [May 4, 2021, 10:16pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/10 "2021-05-04T22:16:00Z")

</div>

@sylvaticus thanks I totally agree that I will need to make the SoiulWater-ToolBox into a package, I would write a dedicated topic to answer some of my questions.

---

<div class="post-metadata">

**Author:** ![JosephPollacco](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/josephpollacco/32/51404_2.png) [@JosephPollacco](https://discourse.julialang.org/u/JosephPollacco)\
**Post date:** [May 4, 2021, 10:17pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/11 "2021-05-04T22:17:15Z")

</div>

@sylvaticus The conference looks very interesting 😃 Yes I am French scientist but working in New-Zealand.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [May 4, 2021, 11:27pm UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/12 "2021-05-04T23:27:03Z")

</div>

> [@JosephPollacco](#):
>
> I am wandering if there are some _Tutorials_ or _Videos_ or **simple example** _templates_ which can help beginners to get started quickly?

My suggestion, after having struggled with that is to copy the structure of the docs of some package and modify files accordingly.

To publish, I have a detailed step by step here: [Publish Docs · JuliaNotes.jl](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/)

This package (JuliaNotes.jl) , by the way, is _only_ docs, thus the structure can’t get much simpler than that. That is a good one to copy.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [May 5, 2021, 9:00am UTC](https://discourse.julialang.org/t/what-recommended-tools-to-publish-user-manual-in-github-wiki/60504/13 "2021-05-05T09:00:29Z")

</div>

I integrate the two in the way I described in my own [BetaML](https://github.com/sylvaticus/BetaML.jl) package, you can have a look on the `docs` folder and the `.github/workflows` one, where scripts for GitHub CI are defined.