I agree.The links to the pre-versions are unique for each version, making it possible to compare the versions and follow the progress. Once complete, I’d like it to be shared with a direct URL, like duplicati.com/manual or duplicati.com/manual/stable and duplicati.com/manual/beta. For now I guess the hard to remember and unique URL’s for each preview are not a problem, as long as the manual is used as a preview, without linking to it.
Good one, never thought about that. Can you give an indication what’s the main difference about a general copyright text and the various CC licenses? If the manual may be used and distributed for free, but not exploited commercially and modified only after asking permission (copyright text should be modified a bit to reflect that), how can a CC license add value to that?
I have thought of several options how to share it, but still not sure what the best option is and what’s technically possible. I’m not feeling very comfortable by the idea to put as much as possible in the forum, as I still see the primary usecase for a forum is discussion, mainly “User X helps User Y” and discussions about how to improve the product.
When I download a program I want to try, I first click on the Support/Documentation/Features link and not dive straight into a discussion board to find out how things work.
But nothing has been decided yet, first let’s try to complete the docs as soon as possible. In the mean time, things may evolve, and thoughts may change on what’s the best approach for releasing it to the public.
Did not think about that thoroughly, but this is a problem we are going to face:
Update documentation for every single Canary version seems inconvenient to me. I guess documentation of the latest beta or stable is sufficient to get a Canary user started.
Converting the manual to HTML seems a good way to keep everything up to date. If selected people can update it directly on the website, they can make changes as soon as new features are implemented. If a new beta/stable is released, the most recent Canary can be copied to the manual for the beta/stable version. But ATM I don’t know what’s technically possible.
Granted this is thinking a bit on the small side, but I was imagining a forum topic specifically for the manual in which only certain users / staff have permission to post.
A drawback of this is that the manual is much bigger than Discourse allowed settings (at least current ones) and I don’t know if they can be adjusted at a per-topic level.
The drawbacks of hosting an HTML or PDF version elsewhere, such as on the main Duplicati site, is that very few people have access to make changes to that site so I expect we’d basically be needing to ask @kenkendk to update the site each time a change was needed.
In case it’s plain HTML or a PDF that would indeed be the case. But there are many great open source documentation systems that provide everything that’s needed. Simple user management, multiple editors (even for suggestions only) export to PDF and version control. So that shouldn’t be the issue.
Thanks for the link, this makes it easy to choose the appropriate license type. I’ll wait with a descision until it’s clear where and how the manual is released. Duplicati can be whitelabeled and commercial use is allowed. If the manual can be downloaded from the same location as the software, I guess releasing derivative versions and using it commercially should be allowed for the manual too.
This completes all subjects I want to cover in the manual (General information, Installation, Graphical Interface, Storage Providers, Commandline Interface, Disaster Recovery, Commandline Reference, Advanced Options Reference, selected whitepapers in Appendices).
What I’ve thought about, but didn’t make it to the manual is: “FAQ’s”, “Troubleshooting”, “Specific operations / Hacks / Tips & Tricks”, “Howto’s” and “Using specific Storage providers”. Reasons:
these subjects are quite dynamic (storage providers based on standard protocols like S3 or SSH come and go)
When documenting procedure X, you have to document many other related procedures (example: documenting moving Storage provider X to Y induces the need for documenting a lot of other migration scenarios.
When documenting hacks / special use of Duplicati, there is no rule to choose what to document and what not.
FAQ’s, Troubleshooting and Howto’s are covered nicely by the forum.
Before marking it as final, can anyone give feedback about:
Is there any information that should be covered by the manual that is missing in the latest version?
Can something be improved to the layout or content?
Spelling or grammar mistakes? Please submit!
I prefer receiving issues by PM in an attempt to keep this topic clean. I can fix small problems (typos, adding/changing/removing some words) and report “big” issues (add a subject/chapter, reorder content) that are elegible for discussion back to the forum.
If there’s much to discuss, I could open a new topic for manual corrections.
Yes, I was thinking of something similar except that I wouldn’t put the entire manual into a single topic but create a separate topic for each section or even subsection. It probably depends a bit on the nature of the sub-section. If you decide to put more than a sub-section into one topic, I would definitely put the sub-sections into separate posts (which could all be linked in the first post as a kind of TOC).
All those topics could then be tagged “manual”.
I would avoid the NoDerivates part because that would prevent people from extending, updating, and improving the manual. You might even want to consider allowing commercial use. We tend to think that it simply means that you are not allowing anyone to make money from your work. But NonCommercial is quite a bit more restrictive than that. Take for instance the (quite realistic) scenario where a computer magazine wants to put duplicati on a DVD that is attached to next months edition. If the manual is licensed “NonCommercial”, they are not allowed to include the manual on that DVD.
BTW, if you’re not aware: you can easily print any forum topic as a pdf. Try pressing Ctrl + P right now.
So another way of going about this would be to actually use the forum as your editor when writing the manual. The downside would be that the entire manual would have to be in a single topic (though it could still consist of many posts) and that topic would then obviously restricted for posting by staff only so that users would not be able to comment by replying directly on a specific post. But, as I think of it, maybe that is not such a big problem after all because:
they can still quote any part of the manual with ease
the manual topic may be much more accessible because you only see the manual (and are not distracted by comments and questions)
When you are reading the manual topic you will still see links under each post, indicating if there has been any discussion on that part of the manual
I guess I don’t need to explain the huge advantages this way of working would have for keeping the manual updated…
@kees-z, I can hear you thinking: why are you telling me that now that I have written the bloody thing in a text editor? (At least that is what I would think.) So if you want to transfer the manual to a topic, I’m offering my assistance in moving everything over. (In that case, please send me the non-pdf version of the text)
In my view the best way to generate a manual is currently using https://readthedocs.org/ I find it very simple how it works, so much so that most of the opensource projects I use currently use this platform to generate their manuals .
As it works in the form of a wiki with a simple interface to use, this helps a lot because it can be used in the future to generate versions for several languages in a simple way.
Here is an example of a manual / documentation using the tool. http://nxfilter-br-tutorial.readthedocs.io/en_us/latest/
I’m still thinking of what would be the best way to publish it, I guess we all agree it should be put somewhere online for easy access and updating. Until the manual is completed, there’s time to think it over. I’m open for suggestions.
For now, I prefer something like https://readthedocs.org/ or http://www.mkdocs.org/ above putting the complete manual in forum topics. However, I’m not familiar with any of the solutions, but I guess all of them require major reformatting.
I guess the requirements for a solution like this are (in order of importance):
Clean, nice, customizable design with easy navigation for end user through the sections.
I’m not sure whether I was unclear in my earlier post above or whether my suggestion is just unpopular. While the latter would be okay with me, let me just point out more clearly the possibility of using this forum to publish the manual: what I meant was indeed that the forum can (for our purposes) replace services like https://readthedocs.org/ or http://www.mkdocs.org/. Earlier I suggested to
But I later realized that it is not really necessary to publish the manual elsewhere at all. I someone wants a pdf version of the manual, we can just provide a link like this: “Download print version of the manual here”
I’d say that it fulfills all of these criteria
plus at least two bonus criteria:
Users will be the same user accounts as the forum users, making permission management very easy (not only for existing staff users but it will also be very easy to give permission to other forum users who are willing to contribute and they will not have to learn another system/create another account)
The manual will be searchable/discoverable for anyone searching the forum without any need of copying “the real” manual over and essentially keeping two versions up-to-date.
Now, if you look at my pseudo manual link and think the “clean, nice design” criterion is not full met because the pdf includes for each post the author name, date and time, I’d agree. But this can probably be easily fixed by adding some CSS (only admins have access to that, so don’t try to find it).
I perfectly understand what you mean. Discourse is a great platform with features that allow you to use it for all kinds of purposes, but in the first place it is a discussion platform, not a system for managing documentation. Although I love the look-and-feel, it lacks features that makes management of documentation comfortable and easy.
I don’t know which features are included in the other mentioned products and how easy they are to use, but there is a number of options that cannot be found in Discourse (I guess). I hope to find most of these features in ReadTheDocs, MkDocs or other similar products. Using Word, I intensively rely on features like auto-numbering (multiple levels deep), auto formatting, automatic creation and update of the TOC.
The features of the mentioned (and still unmentioned) products are still unknown to me, but I’d like to compare them thoroughly before making a final decision. However, my preferred solution is something that can be easily kept up-to-date with lots of options to (auto) format the text.
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…