which wiki system for a documentation

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
bernd
Posts: 8233
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

which wiki system for a documentation

Postby bernd » Thu Dec 20, 2018 6:49 am

I need to set up some documentation in our company. ATM the idea is to use word processor for this. IMHO this is complete obsolete way of doing documentation. What would you guys use if you could set up something from scratch ?

- word processor
- media wiki
- other wiki
- readthedocs
- what else

I remember we had a discussion about better documentation system than media wiki for FreeCAD, but can not find the topic

cheers bernd
User avatar
yorik
Site Admin
Posts: 11458
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: which wiki system for a documentation

Postby yorik » Thu Dec 20, 2018 2:13 pm

my own opinion is: a git repo with markdown files. This can easily be exported to several platforms for translations, online formatting/reading, and ebook generation...
Le_Loup
Posts: 16
Joined: Sun Apr 08, 2018 10:00 am

Re: which wiki system for a documentation

Postby Le_Loup » Fri Dec 21, 2018 12:18 am

I'm not sure whether markdown supports things like "indexing"/"links" (and other things helpful for longer documentation) out of the box. In HTML one was able to insert a "tag" which was added to an index and you could jump to it. In markdown I missed such things some time ago. It may have been added, though... (I'm not sure about the HTML terms, so "tag" etc. might be wrong).
User avatar
yorik
Site Admin
Posts: 11458
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: which wiki system for a documentation

Postby yorik » Fri Dec 21, 2018 12:24 pm

This is usually auto-generated by the system that you use to "publish" the markdown files, from the ## (any number) titles. For ex, github does it. You can write a link like this: [My Link](somepage.md#sometitle)
User avatar
bernd
Posts: 8233
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: which wiki system for a documentation

Postby bernd » Fri Dec 21, 2018 3:50 pm

What did you use to write the FreeCAD book yorik?

Readthedocs does exatly this (what yorik described) with the bound of markdown files, AFAIK?
User avatar
yorik
Site Admin
Posts: 11458
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: which wiki system for a documentation

Postby yorik » Sat Dec 22, 2018 2:57 pm

I basically used https://www.typora.io , I really like it. But there are hundreds of other markdown editors out there. I like markdown because it's as simple as wiki syntax, but more portable and it also looks good simply viewed in a txt editor.

Then I just saved my files in a git repo, one file per chapter, and one directory for each "section" of the book. But there you are pretty free to organize like you want. Then, usually each publishing platform (gitbook, readthedocs, etc) asks for a config file to be placed in the repo, a bit like the CI sites do.
User avatar
bernd
Posts: 8233
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: which wiki system for a documentation

Postby bernd » Sat Dec 22, 2018 9:27 pm

Slowly I get into all this ... :)

@Yorik: How about reStructuredText? There are lots of disscusions which one to prefere reStructuredText or Markdown? Have you thought about this too?

cheers bernd
User avatar
yorik
Site Admin
Posts: 11458
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: which wiki system for a documentation

Postby yorik » Sun Dec 23, 2018 1:20 pm

I never really had a deep look at restructuredtext... Markdown is so easy :)
ubiquity
Posts: 32
Joined: Fri Nov 03, 2017 7:40 pm

Re: which wiki system for a documentation

Postby ubiquity » Sat Jan 05, 2019 4:31 am

@bernd I like the look of Readthedocs and LibreCAD has set up a project there to explore the possibilities and the Godot Engine is a good example (mentioned in my recent thread on Broader Documentation As is a link to an article on forms and purposes of documentation https://www.divio.com/blog/documentation/.

If you have authors willing to contribute in word processing (perhaps because it is the most familiar tool) then have a look at Pandoc which claims to translate between document formats. I haven't used it but it might be useful.
OS - Linux Mint 19 & Win10 (both 64bit)
IT Training & Support (retired)
Cheers Paul