If that is your priority, there is no need to look further. Because maintaining a manual in the same system where support discussions take place is arguably the easiest. And as regards formatting, discourse is very flexible as it supports Markdown, BBCode, and simple HTML.
But I understand your urge to compate products. I am also a comparer (though I have less and less time for that). So if you want to compare products, I’d suggest that you include discourse in your list of products. I have so far based my recommendation on the criteria that you mentioned (plus two of my own). It is entirely possible that discourse will not do as good if you add other criteria. So once you have those criteria, I’ll be happy to revise my recommendation.
If you’re wondering about whether discourse can do something, let me know.
Hi, I just want to throw my two cents worth in here.
I helped with documentation for another open source project in the past and the things I found were helpful was that:
that documentation was built around a wiki. This meant that any member of the community could update it, and honestly, that is how I got started with it. One day I was just frustrated with the lack of documentation on a point and so I documented it, then I got to documenting more and more because I realised how easy it was to do so.
being a wiki, it could be translated by google translate, so it was accessible to a wider audience. PDFs can’t easily do that.
being a wiki, I could also download it and use a static offline copy as well (granted a PDF is prettier)
being a wiki rather than a PDF meant that when people asked questions about things in the forums we could link to exact pages in the documentation that had the answers.
I like some of the tool suggestions that people have been making here - anything that creates web content that has static urls is a good thing for me as it addresses all the things above that I thought were beneficial from my previous experience. I do like discourse (very impressed with this forum which is my first experience of it) but I am not a fan of cluttering the forum with documentation. I see forums a source of information that can be used to build the documentation, but not documentation itself. My approach, having only entered this community recently, has been to go through the forum answering questions for myself and then print those out as PDFs using my browser so that I have an offline reference to different topics of information. But if that content was then added to a manual, even better!
I hope this helps. Well done on the start that has been made on the documentation so far! Could it be linked somewhere that is easier to find though? I’m at week 2 of duplicati but I’ve only just discovered it. It would have been a nice place to start in week 1.
I joined the forum solely over a huge concern for this post, what an awesome project, but the documentation is struggling hard, Stephens post is a bulls eye, and I just want to give support towards that.
I dont know why people keep talking about different methods of open source documentation. A wiki seems to be the standard pretty much across the board these days.
The PDF is nice, and I appreciate the immense amount of work that must have gone in to the ~160+ pages, but I dont think it is going to flow at the speed of the project, nor serve its users. I can appreciate your choice of an ember forum for its simplistic yet sophisticated functionality, but this is still not the place to put documentation, not even in sticky posts - typically a sticky is just to point people to the … Wiki.
Wikis are a very basic method of conveying info in kind of a topic/outline form (if done right…some just ramble), with a logical navigation. Github already has a wiki built in, and I see some content in there - why not stick with it or mediawiki?
Finally - try to make it community driven, 3-4 forum admins are going to have a hard time keeping up with docs, a forum, and god forbid development. I work on a few projects where I notice “hey that was from 3 versions ago, this feature is completely different now, let me append the latest version info to this page… or at a minimum put a note at the top ‘deprecated now’…”. You might have an intro message go to new accounts “please post in xyz manner, ie post pertinent version info, dont delete old content that may apply to existing popular user base, etc.”
And I might add that any post on this forum can be converted into a wiki (i.e. it becomes editable by almost anyone).
And there is no contradiction between the wiki and pdf format:
Why “cluttering”? Nobody is a fan of cluttering. But there is no reason why hosting the documentation would produce clutter. Why shouldn’t the forum be both a source of information for the documentation and the documentation itself? Here is what I suggest:
Activate the category setting Make new topics wikis by default
Split @kees-zmanual into meaningful chunks, each of which becomes a topic of its own. (Copy and paste will be easy, since it’s already in MarkDown)
Possibly create yet another topic which serves as table of content with links to all the other ones (also a wiki, of course)
Done! (for now. Refinements possible.)
I don’t have a clear opinion on whether replies to these documentation topics should be allowed but I tend to think that it’s a good idea as it makes it easy for people to ask questions directly related to the documentation (if a reply (or a series of replies) doesn’t add to the documentation, it can easily be moved into a support topic of its own (which will remain linked in the docu topic). But friends of printed manuals may prefer to keep all questions and discussion outside the docu category…