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
which wiki system for a documentation
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: which wiki system for a documentation
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...
Re: which wiki system for a documentation
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).
Re: which wiki system for a documentation
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)
Re: which wiki system for a documentation
What did you use to write the FreeCAD book yorik?
Readthedocs does exatly this (what yorik described) with the bound of markdown files, AFAIK?
Readthedocs does exatly this (what yorik described) with the bound of markdown files, AFAIK?
Re: which wiki system for a documentation
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.
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.
Re: which wiki system for a documentation
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
@Yorik: How about reStructuredText? There are lots of disscusions which one to prefere reStructuredText or Markdown? Have you thought about this too?
cheers bernd
Re: which wiki system for a documentation
I never really had a deep look at restructuredtext... Markdown is so easy
Re: which wiki system for a documentation
@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.
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
IT Training & Support (retired)
Cheers Paul