Wow, it never occured to me to try that. I think that helps a lot–thanks.
Probably one of the biggest limitations right now for Duplicati is the lack of a thorough, up to date manual that helps the user along with little details like this, as well as step-by-step on some items. I realize that the program is still in development, the developers probably don’t have time to work on a manual which will be constantly changing, and that most of those who are following the program are more savvy (and multi-platform aware) than some users who might be interested but a bit perplexed by some stuff. Still, it I think it would help if people who stumble across Duplicati feel more invited to stay, or to consider coming back if things have not quite gelled for them. Having more description of what the program does and what to expect in the future would help build your audience.
Not sure how this should work, but for now I am trying to do this in terms of “how-to”'s (see How-To for progress). There is also a very bare-bones “getting started” guide here:
Maybe we should link to that article, or the how-to’s from the WebUI ?
The how-to’s are good–thanks for sending me there, in fact I just found a thread that might address another issue I have, and I just posted there. I was thinking more of a step-by-step guide how to do various things. The Getting Started Guide seems essential for the basics, but as you said, it is really bare-bones. it would be good if there were more detail about specific issues one might run into, or perhaps links to threads at certain points in the Guide, to where that issue was gone into in detail.
I think I understand what you are requesting, but I have a hard time imagining what kinds of issues people have, and what kind of details are required.
In other words, if I were to write such guides, I would need some keywords or topics, and maybe I could write posts based on that.
I imagine you have your hands full just keeping up with the code writing you want to do and that people are requesting.
I wonder if the detailed guide or User’s Manual could start somehow as a community effort. Maybe some active users could draft guides on particular issues they had to figure out for themselves and they now feel they understand well enough to help others with it. Hopefully, they would have reasonable writing skills, of course, but they would submit their draft to you, and you would edit for accuracy, without having to do all the writing from scratch. Perhaps the first step would be to create an outline of what needs to be in such a manual–your suggested list of “keywords and topics”, then how it would be organized. Then people could pick topics to write about. This would be an interaction between users and you, so I’m not sure how it would go. It wouldn’t be a simple process, but maybe it could save you time and result in a more complete manual over time.
…In my vision, this evolves organically. If it just turns to chaos, I guess you just stop the train and get off for a while…
I think that’s the sticking point - were so close to the functionality that it’s hard to pretend we’re new users not knowing what to do.
Is this something you imagine living online or as part of the installation? Is it safe to assume command line users are less likely to need such content and less-techy GUI users are less likely to know how to dig through the forum?
Personally I think some well placed in-GUI links to a few of the YouTube videos people have made is a nice soft start for things like:
installing as a service and why you might want to
creating your first backup job to a USB drive
creating your first backup job to Amazon / S3
creating your first backup job to Google drive
choosing what to back up
applying backup filters
applying advanced backup filters
scheduling backups
manually running, pausing, and canceling backups
restoring files / doing a test restore
configuring notification emails
configuring advanced notification emails
exporting / importing backup jobs
seeing what was backed up / introduction to the command line interface
seeding backups / changing destinations
using the forum for support (including exporting tp command line)
Etc., etc.
I purposefully excluded anything related to “how to use the GUI” because if we have to explain it then the GUI needs to be updated.
@Bilateral: I fully agree with you. An extensive manual describing all features thoroughly might add much value to Duplicati.
I’m quite familiar with most features in Duplicati, but there are many options and features that I didn’t think of until reading about them by chance somewhere.
A good manual should describe the concepts, system requirements, installation, usage (first use/getting started/step by step), maintenance and all individual features. An extra section for all command line options should be added. This manual could be offered as a PDF or online (or both). A nice manual of another backup solution can be found here: https://www.altaro.com/userguide7/
Backdraws of such a manual (and I think these are the main reasons why still no manual has been written) are:
Writing a manual is a very time consuming task. It should cover every feature that Duplicati offers. At the moment nobody seems to be available with enough time, writing skills and in-depth knowlegde.
Once completed, the manual should be maintained. New features should be added, changes in the software should be fixed in the documentation, screenshots should be updated etc.
Trying to develop a manual by the community sounds like a great idea. If there are enopugh volunteers who are willing to write one or more sections, I guess this would be the best option. However, I’m not sure if enough volumteers can be found who are willing to contribute.
But once complete, I suppose a lot of support requests can be answered by refering to a specific section the manual which might significantly save time. New users can be guided step by step with installing, configuring and using Duplicati. Advanced users can pull the most out of Duplicati by using the manual as a reference for tweaking advanced settings.
I believe this will help new and experienced users better than an inconsistent set of articles that describe very specific issues.
Although translated versions are more than welcome for me, I suppose an English version should suffice for almost all users. This forum, all articles and the website are English-only too. The fact that people find, download, install and use it indicates that an English manual will serve most users.
It does seem like a daunting project. It has to start somewhere, though. I think if everyone waits until the software is perfected to start writing a manual, it will only get more daunting, and it may never get done. Would be better if it started now and could grow with the software. But it’s hardly brave of me to say so; I barely know the program yet, so I will not be writing any manual pages. But such a project would need a project manager to keep it moving along.
BTW, I’ll see if I can change the title of this thread to add the manual discussion to it.
Thanks for considering that, but at this point we’ll probably spilt the documentation discussion to it’s own topic so potential contributors aren’t bogged down reading non-manual stuff.
That looks like a great start and for now it’s good to have it in a document. But when it’s (almost) finalized I think it would be a good idea to publish it online on a webpage. That would make searching through it easier and that way multiple managers could be assigned to keep it up2date.
Maybe wiki style with readers suggestions that can be approved?
Yes, that looks nice. The same idea as this or this manual.
Once complete, I suppose that the document with more or less effort could be converted to something like these online manuals. From that point, keeping the documentation up-to-date will become easier, because more than one person can be given access to it.
That would indeed be a good idea, but from an SEO point of view (and for people that read up before they start) an online version should be there as well.
Agreed. Not everybody will use the UI and having it on the web means there’s at least a possibility of Google offering to translate it for those that might not know English very well.
Added Chapter 3 (Using the Graphical User Interface), making the manual a bit useful.
Almost hitting the 100th page. Never thought it would be such an extensive report. Still a lot to add.
I used to write end training manuals for SAP. Best part of the day was seeing how wide people’s eyes got when seeing the size of the training docs for the first time. 8-O
This is really good; it’s exactly what Duplicati needs. However, you haven’t yet covered the main command line application, Duplicati.CommandLine.exe. It took me some time to figure out how to use the “find” command with my local database. Duplicati really needs more documentation and FAQ’s.
I’ve had so many questions along the way when trying to use it for the first time, like whether I can clone my entire backup to another location (rather than just cloning the configuration); haven’t seen anything on that so I had to run the initial backup sequence twice… I’ve been wondering if it would be possible to hook up common diff tools somehow, if I could somehow commit backups without having to store the uncommitted files first, whether there are potential dangers if I move around the source or destination folders, etc.
As for the rest, is it stuff you want to know or stuff you figured out on your own?
Documenting a tool like Duplicati can be very difficult because of the various usage scenarios different users might find for it. If we document them all then the manual will be so big it would scare most users away.
That’s partly why the forum was started just a few months ago - to provide a place for users to ask questions not covered by the existing “most common use” documentation.
Most of the stuff I have not yet figured out and still don’t know how (besides just asking each question). People don’t want to bother asking 10 questions just to figure out how to use a product. There’s a certain ratio of botherability, and the less a person has to bother, the more likely they will use and continue to use a product. It will also give them more confidence while they are using it.
You could take the Resilio Sync and Mozilla Firefox approach, which I really like: answer many various questions in the form of mini-articles (about the size of a single category in the existing Duplicati articles up to half the size of those articles) and keep them organized. Then, provide a search function and the ability to submit new questions and give feedback. This kind of help is not daunting at all; it is inviting.
Revision 0.4 to serve commandline lovers: added commandline tools description, advanced options and a few appendices. Document has grown to 147 pages. Phew!
It’s getting more and more complete, but some information still should be added. At the moment I’m working on a description of the Duplicati.CommandLine.RecoveryTool.exe tool. I guess this tool needs some special attention, because it provides some insight how the backup and restore process works. In addition to that, this tool plays a crucial role in disaster recovery scenarios. So what’s available is still a pre-release, some essential info is still missing.
I upload these early versions, hoping that one or more reviewers read the full text and submit corrections. English it not my native language, so there might be some spelling errors and weird sentence structures.
Once complete, I can think of the following uses:
Add a link to the PDF on the website
Include the manual in the installation packages
Somehow convert the PDF to HTML and publish it somehow like this. This also makes it easier to keep the documentation updated. Maybe the online documentation can be easily converted back to PDF for inclusion in the install package.
Regarding publication of the finished document I’d like to suggest three things:
publish the pdf under a single URL, so one knows where to find the latest version (ideally, the url doesn’t change when the document is updated),
publish it under a creative commons license (or the like) instead of copyright
copy and paste each section (or sub-section) into a new topic here on the forum to make it searchable. It’s probably also a good idea to add a link to the pdf manual at the beginning of each post, mentioning that what follows is an excerpt of that manual.
I don’t think that’s the best way to put a manual online. There are multiple open source alternatives for this that will make reading through it easier and information searchable. Manual in a forum are always more messy and multiple editors is more difficult to manage.
The point here is not to put a manual online. That is done by publishing the pdf document (or whatever the preferred method may be). The point is to make the information in the manual discoverable for people coming to the forum with a support issue.
That I understand, but what’s wrong with linking to a different part of the website where the manual is available. I think for maintaining the manual its easier to do it from a descent system, a forum isn’t really the tool for documenting a manual.
As a side note: a PDF isn’t really the way to go either. It’s nice if it could be exported for offline and printing purposes but online is better searchable and linkable (same for indexing in search engines).
It depends what kind of manual you want to offer to users and, importantly, how much time and effort do you want to invest in producing and maintaining it. Personally, I would not invest the time for making an old school manual (pdf) but I appreciate it if it exists. I have also argued against a knowledge base type “manual” because it requires a lot of work to maintain, plus: we would then have two (or three, if a pdf version also exists) separate support locations. That is why I strongly argue for making all support information searchable here on the forum.
And I would argue that duplicating the pdf manual on the forum is also a goid way of keeping the manual updated and incrementally improving it because if there is something that users don’t understand or that no longer seems to work, they will comment/ask on the forum, thus making that information immediately available to everyone and whenever someone takes the time to update the pdf document, they can just look through the comments on the forum to find those points that need updating.
One thing I forgot to mention earlier is that linking from the pdf to the respective forum topic would be another plus (like: For further information on this, see {link to forum tooic}).
So, in other words, I see the manual as a structured/guided access path to the forum.
Not to make things any more confusing, but do we have a versioning plan?
For example, there are a lot of users on 2.0.2.1 beta who are not interested in running on a canary version. But there are a lot of features new to canary.
Will only beta, or even only stable, versions be documented in this fashion? Or will the single document include notes of what versions certain functionality was added or removed?
Assuming a future version is as much a UX change as 2 was from 1, do we want to have multiple versions searchable?
I guess it depends on the publishing way that will be chosen. I think there is already sort of an agreement that (only) PDF isn’t the best way. A PDF is sort of a final version and harder to maintain, so in the future I would say only stable versions and for now only beta.
Though if a part of a knowledge base or forum is exportable as PDF it could maintain everything. A beta release manual that contains all updates will eventually become the new stable one and same for Canary version that becomes a beta (though canary will be harde to keep up with).
In do agree with parts of your opinion and understand what your reasons are. But the quote above is why I would separate it.
For users that want information about how something works the forum would give to many hits and would make it even less clear for the person in which topic they are talking about which version. If they want to know how function X works they need an answer / manual, not results from a forum about people having issues with that function etc. But that’s my opinion
A search can be limited to a single topic which might help with that, if an in-forum version is made. Though making it clear that’s a “preferred” way to search it is questionable.
Or a single category. Or a single tag (e.g. “manual”). Or a specific user…
In addition the search function is smart in that it prioritizes posts based on various stats (which is why it’s important to like useful posts and cross-link to relevant posts) so that chances are that manual posts would easily be found even without using advanced search.
Having a version of the manual on the forum in the form of topics doesn’t prevent anyone from looking at the pdf version of the manual (if they can’t find the relevant topic on the forum).
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.
Nice, huh?
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)
Anyway, since @kees-z is doing the hard work, I think he can decide how it should be done. I will be happy to assist in getting it hosted when it is ready (send me a PM).
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…
