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.
