which wiki system for a documentation

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Post Reply
User avatar
bernd
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

which wiki system for a documentation

Post by bernd »

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
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: which wiki system for a documentation

Post by yorik »

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: 20
Joined: Sun Apr 08, 2018 10:00 am

Re: which wiki system for a documentation

Post by Le_Loup »

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
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: which wiki system for a documentation

Post by yorik »

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
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: which wiki system for a documentation

Post by bernd »

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
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: which wiki system for a documentation

Post by yorik »

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
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: which wiki system for a documentation

Post by bernd »

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
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: which wiki system for a documentation

Post by yorik »

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

Re: which wiki system for a documentation

Post by ubiquity »

@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
Post Reply