Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 04.07.2012 00:04, schrieb Aurélien Gâteau: Le mardi 3 juillet 2012 18:24:41 Ingo Malchow a écrit : In an ideal world we could really work around such issues with some semi-automated ways. Just an idea: Those who do like the idea of doing a manual in a online wiki could just teach their respective users how to properly format their manual. This reduces the overhead on developers, but also improves the integration of user contribution. Once a release is about to happen the page can be closed (protected from further editing) and exported to docbook and put into some git/svn repo. This needs some adjustments on the docbook export, but those are technical details, so i skip that here. At the same time our group leaders for languages can be poked to review their translations on the current state of it. Which is AFAIR the workflow on the offline translations as well. Now you can easily translate on- or offline in the usual way and it can finally be merged in the final manual release. As sidenote for those without internet, we can also produce a pdf at release dates, not sure everybody is aware of that. I like your idea: it let users collaboratively write documentation on the wiki, while still making it possible to produce formal offline-usable manual at release time. The only thing which worries me is updates of stable versions of the manual: is it possible to maintain stable and master versions of the documentation in the wiki? Aurélien This is indeed not possible in a wiki without copying content to 2 different locations. But that shouldn't be too complicated to fullfill. - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/z4dMACgkQgFDgF4YW7sd5mwCeJpsBZXYBSXWIBMdwKkh+t5eo z28An1J5MRrBh2bojX//C+shNN5Tdx2w =08Xf -END PGP SIGNATURE-
Re: Using userbase for manuals
[: Aurélien Gâteau :] I know at least one wiki which is git-based: [...] [: Ingo Malchow :] [...] Additionally we will loose support for quite some plugins, most notably the translate extension, which is integral part of this entire discussion. So we would be back at manually copying the english original and translating an entire page without being notified of further changes to the original. Maybe, but not relevant. Every conceptually different documentation workflow needs specialized translation workflow (or specialized adaptations to an existing translation workflow). VCS-wiki combined workflow is conceptually different from VCS or from wiki workflows alone, so it would need yet another specialized adaptation for translation. Which is just fine, so long as there is someone to do that job. All that for the sake of using a commandline tool instead of a browser? This sentence represents a deep rift in thinking. Which is just fine. There is no need at all for everyone to use the same documentation workflow. Consequently, there is no need to decide about which one workflow that should be. Instead, every project should pick its documentation workflow/ format, either one that is already integrated to some degree into KDE technical structure (currently: in-repository Docbook, over-the-web MediaWiki), or something else. This choice should be made by the documentation maintainer for the given project. In their choosing, most projects will want to take into account possibility of translation too. If translation mechanics are not already in place, project maintainers may add it themselves, or find someone else available to do that. In the case of a new (non-Docbook) strictly in-repository workflow -- documentation source strictly found in project's code repository and strictly updated in usual VCS fashion -- I will be that someone else available. I will make translation mechanics smoothly integrated into workflow of traditional KDE translation teams (the people who now maintain translations of 1,100,000 words of documentation). When you have written and plan to maintain (as opposed to ooh, I'm sure it'll be just great) some such documentation, write to kde-i18n-doc or to me directly to arrange for translation. Another point, about converting to Docbook that is mentioned in several contexts, both in this thread and before. There is only one and a half case where this is sensible. One is when you are picking up maintenance of a given piece of documentation, and your preferred format is Docbook. The half-case is as a kludge in build chain, such that the Docbook files are temporaries, or analogous to installed binaries. In any other context converting to Docbook is plain wrong, so forget about it. -- Chusslove Illich (Часлав Илић) signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
On Sunday 1 July 2012 09:49:11 Kevin Ottens wrote: [...] My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. Actually, after sleeping on it, it made me realize that this point above renders the discussion moot from a KDE Frameworks standpoint. On my side I was trying to determine if we had a way out from invokeHelp(). But as soon as you need this type of extra behavior, you need to have something like invokeHelp(), so our solution doesn't lie with the wiki or docbook discussion. Anyway, thanks everyone involved for the input provided. It was also a good opportunity to evaluate how our current doc team perceive userbase use for manuals (although that was just a fringe interest from KDE Frameworks perspective), I think the outcome there is pretty clear. :-) Regards. -- Kévin Ottens, http://ervin.ipsquad.net KDAB - proud patron of KDE, http://www.kdab.com signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
Le lundi 2 juillet 2012 07:01:06 Inge Wallin a écrit : Now, the suggestion was to move to a wiki instead Advantages: 1. Easier to find the documentation for potential writers. 2. (Supposedly) easier to edit [Personally I'm not sure that editing advanced wiki markup is easier than docbook] Disadvantages: 1. Difficult to maintain different versions of the documentation for different versions of the software. 2. Users need to be online to view the documentation. I think that calling this problem vanishingly rare is a very northern Europe centric view. And even I who have excellent broadband often still do work offline sometimes. Have it been considered to use a git-based wiki? Such a solution could make it possible to: - keep documentation within the code (or close enough) - web editing for people who are not familiar with git, offline editing for advanced users (or for when you want to write documentation offline) - branching the documentation to follow versions One could probably produce offline KHelpCenter-compatible documentation from it. I know at least one wiki which is git-based: Ikiwiki [1][2]. I have no idea if it can be adapted to our needs, but I think it is an approach worth looking at. [1]: http://ikiwiki.info/ [2]: https://en.wikipedia.org/wiki/Ikiwiki
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 03.07.2012 14:00, schrieb Aurélien Gâteau: Le lundi 2 juillet 2012 07:01:06 Inge Wallin a écrit : Now, the suggestion was to move to a wiki instead Advantages: 1. Easier to find the documentation for potential writers. 2. (Supposedly) easier to edit [Personally I'm not sure that editing advanced wiki markup is easier than docbook] Disadvantages: 1. Difficult to maintain different versions of the documentation for different versions of the software. 2. Users need to be online to view the documentation. I think that calling this problem vanishingly rare is a very northern Europe centric view. And even I who have excellent broadband often still do work offline sometimes. Have it been considered to use a git-based wiki? Such a solution could make it possible to: - keep documentation within the code (or close enough) - web editing for people who are not familiar with git, offline editing for advanced users (or for when you want to write documentation offline) - branching the documentation to follow versions One could probably produce offline KHelpCenter-compatible documentation from it. I know at least one wiki which is git-based: Ikiwiki [1][2]. I have no idea if it can be adapted to our needs, but I think it is an approach worth looking at. [1]: http://ikiwiki.info/ [2]: https://en.wikipedia.org/wiki/Ikiwiki There is also gitit. But from what i can tell, they don't provide a way to import content from mediawiki. And looking at the number of pages our wikis have at this stage, this is a major drawback. Additionally we will loose support for quite some plugins, most notably the translate extension, which is integral part of this entire discussion. So we would be back at manually copying the english original and translating an entire page without being notified of further changes to the original. All that for the sake of using a commandline tool instead of a browser? - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/y8S0ACgkQgFDgF4YW7se/iwCePyJqWPKlpcNU0AvRK7MaaMww jt4AoKasW+DmSp7EmDWzSzpc1XQVQNiL =qjP3 -END PGP SIGNATURE-
Re: Using userbase for manuals
Le mardi 3 juillet 2012 15:18:37 Ingo Malchow a écrit : -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 03.07.2012 14:00, schrieb Aurélien Gâteau: Le lundi 2 juillet 2012 07:01:06 Inge Wallin a écrit : Now, the suggestion was to move to a wiki instead Advantages: 1. Easier to find the documentation for potential writers. 2. (Supposedly) easier to edit [Personally I'm not sure that editing advanced wiki markup is easier than docbook] Disadvantages: 1. Difficult to maintain different versions of the documentation for different versions of the software. 2. Users need to be online to view the documentation. I think that calling this problem vanishingly rare is a very northern Europe centric view. And even I who have excellent broadband often still do work offline sometimes. Have it been considered to use a git-based wiki? Such a solution could make it possible to: - keep documentation within the code (or close enough) - web editing for people who are not familiar with git, offline editing for advanced users (or for when you want to write documentation offline) - branching the documentation to follow versions One could probably produce offline KHelpCenter-compatible documentation from it. I know at least one wiki which is git-based: Ikiwiki [1][2]. I have no idea if it can be adapted to our needs, but I think it is an approach worth looking at. [1]: http://ikiwiki.info/ [2]: https://en.wikipedia.org/wiki/Ikiwiki There is also gitit. But from what i can tell, they don't provide a way to import content from mediawiki. And looking at the number of pages our wikis have at this stage, this is a major drawback. Additionally we will loose support for quite some plugins, most notably the translate extension, which is integral part of this entire discussion. So we would be back at manually copying the english original and translating an entire page without being notified of further changes to the original. I don't think one need to have all wiki content transfered to a git-based wiki. I see this as a new tool to collaboratively write documentation which happens to be a wiki, but not necessarily as a replacement for our existing wikis. But then, having different wikis can (will) lead to problems... All that for the sake of using a commandline tool instead of a browser? Being able to use a commandline tool is just a (nice) side-effect. The main advantage of a git-based wiki is being able to branch the wiki for releases. Aurélien
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 03.07.2012 18:07, schrieb Aurélien Gâteau: Le mardi 3 juillet 2012 15:18:37 Ingo Malchow a écrit : -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 03.07.2012 14:00, schrieb Aurélien Gâteau: Le lundi 2 juillet 2012 07:01:06 Inge Wallin a écrit : Now, the suggestion was to move to a wiki instead Advantages: 1. Easier to find the documentation for potential writers. 2. (Supposedly) easier to edit [Personally I'm not sure that editing advanced wiki markup is easier than docbook] Disadvantages: 1. Difficult to maintain different versions of the documentation for different versions of the software. 2. Users need to be online to view the documentation. I think that calling this problem vanishingly rare is a very northern Europe centric view. And even I who have excellent broadband often still do work offline sometimes. Have it been considered to use a git-based wiki? Such a solution could make it possible to: - keep documentation within the code (or close enough) - web editing for people who are not familiar with git, offline editing for advanced users (or for when you want to write documentation offline) - branching the documentation to follow versions One could probably produce offline KHelpCenter-compatible documentation from it. I know at least one wiki which is git-based: Ikiwiki [1][2]. I have no idea if it can be adapted to our needs, but I think it is an approach worth looking at. [1]: http://ikiwiki.info/ [2]: https://en.wikipedia.org/wiki/Ikiwiki There is also gitit. But from what i can tell, they don't provide a way to import content from mediawiki. And looking at the number of pages our wikis have at this stage, this is a major drawback. Additionally we will loose support for quite some plugins, most notably the translate extension, which is integral part of this entire discussion. So we would be back at manually copying the english original and translating an entire page without being notified of further changes to the original. I don't think one need to have all wiki content transfered to a git-based wiki. I see this as a new tool to collaboratively write documentation which happens to be a wiki, but not necessarily as a replacement for our existing wikis. But then, having different wikis can (will) lead to problems... Indeed, and probably one of the times where diversity is not necessarily improving the situation. It might only lead to just another tool, which is a) not used or b) used and reduces quality of existing other wikis due to missing motivation, which are - if i understood correctly - not supposed to be closed. All that for the sake of using a commandline tool instead of a browser? Being able to use a commandline tool is just a (nice) side-effect. The main advantage of a git-based wiki is being able to branch the wiki for releases. Aurélien In an ideal world we could really work around such issues with some semi-automated ways. Just an idea: Those who do like the idea of doing a manual in a online wiki could just teach their respective users how to properly format their manual. This reduces the overhead on developers, but also improves the integration of user contribution. Once a release is about to happen the page can be closed (protected from further editing) and exported to docbook and put into some git/svn repo. This needs some adjustments on the docbook export, but those are technical details, so i skip that here. At the same time our group leaders for languages can be poked to review their translations on the current state of it. Which is AFAIR the workflow on the offline translations as well. Now you can easily translate on- or offline in the usual way and it can finally be merged in the final manual release. As sidenote for those without internet, we can also produce a pdf at release dates, not sure everybody is aware of that. Much of it needs some admin being around, but that is not a problem anymore these days, response time is usually less than a day. This is just an idea which could improve the combination of both workflows, as i see benefits in both of them (vcs vs. web) Cheerio, - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/zHMkACgkQgFDgF4YW7se18ACfT6U91LaFVRwXk7R+5mgxEYTS 0XIAoKsBKJVMKhLi3XJB7Ijs3kM0EZkk =UNU0 -END PGP SIGNATURE-
Re: Using userbase for manuals
Le mardi 3 juillet 2012 18:24:41 Ingo Malchow a écrit : In an ideal world we could really work around such issues with some semi-automated ways. Just an idea: Those who do like the idea of doing a manual in a online wiki could just teach their respective users how to properly format their manual. This reduces the overhead on developers, but also improves the integration of user contribution. Once a release is about to happen the page can be closed (protected from further editing) and exported to docbook and put into some git/svn repo. This needs some adjustments on the docbook export, but those are technical details, so i skip that here. At the same time our group leaders for languages can be poked to review their translations on the current state of it. Which is AFAIR the workflow on the offline translations as well. Now you can easily translate on- or offline in the usual way and it can finally be merged in the final manual release. As sidenote for those without internet, we can also produce a pdf at release dates, not sure everybody is aware of that. I like your idea: it let users collaboratively write documentation on the wiki, while still making it possible to produce formal offline-usable manual at release time. The only thing which worries me is updates of stable versions of the manual: is it possible to maintain stable and master versions of the documentation in the wiki? Aurélien
Re: Using userbase for manuals
On Sunday 01 July 2012 Jul, Yuri Chornoivan wrote: Hi, Just a minor remarks on using UserBase for documentation. 1. It does not matter where you *do not* write your documentation. New Krita manual was started 5-01-2010 [1]. For now, it is not ready even at 1/10 level. The activity is extremely low. The content is badly formatted and hardly useful. Yet, it is 100% more than the effort that was expended on the 2.0 docbook manual. The reasons I never got further were: * no time * I hate writing wiki markup * no time The reason no users took up the effort were: * I mistakenly tried to keep the manual writing to myself, because I thought I could do the job and create a nice, uniform, consistent manual, just like the Krita 1.6 manual, which people have told me was about the best manual of any KDE app. That didn't work out. But without the wiki link, the user currently working on the manual would ever have offered his help. The projection can be made (by exploring similar wiki documentation projects, like Fedora, openSUSE, Mandriva, and Debian/Ubuntu) that when it will be ready it becomes obsolete for the current version. That holds for all manuals... Example of the manual that once was written and now partially outdated is Amarok Manual [2]. 2. Simple conversion docbook to wiki does not make manual useful. Example: Kexi handbook [3] was roughly converted to wiki with broken formatting, lost of index, and no substantial changes. Thanks to Burkhard it was polished (as a docbook) and converted back thanks to Claus Christensen. 3. Manuals can live without wiki conversion. Examples: Calligra Stage [4] and Calligra Sheets [5] manuals were never converted to wiki. For whatever reason, they are now in much more helpful state than Words and Krita docs (not saying that they have offline versions). That's because those applications didn't change so much; it had nothing to do with the conversion to wiki or not, but more with the applications not changing enough to outdate the manual. Because the 1.x krita manual was so good, it was impossible to update it for 2.0; there was too much that was irrelevant, and it needed to be rewritten completely. 4. Proper formatting allows very easy conversion from wiki XML to docbook. Once well-formatted, wiki pages can be converted into offline form (docbook, PDF, or EPUB) in almost no time[6]. Examples: Amarok, Kexi, Kdenlive, KrossWordPuzzle, part of KMail offline manuals are converted (and slightly fixed) UserBase manuals. Just for curiosity, you can compare the level of the translation covering for these docs in kde-i18n Subversion [7] and on UserBase. Conclusion I know that it is hard for developers to keep backward compatibility. But please do not cease to maintain DocBook compatibility in KDE 5. If you do, you will likely lost most of your docs and most of your documentation translators. I am far from making decision for developers, but it is always good to have some plan with real results. Just moving docs in hope that after that someone definitely write them is counterproductive. Just my 2 cents. Best regards, Yuri KDE Ukrainian team coordinator [1] http://userbase.kde.org/User:Boudewijn/Krita/Manual [2] http://userbase.kde.org/Amarok/Manual [3] http://userbase.kde.org/Kexi/Handbook [4] http://docs.kde.org/development/en/calligra/stage/index.html [5] http://docs.kde.org/development/en/calligra/sheets/index.html [6] http://userbase.kde.org/How_To_Convert_a_UserBase_Manual_to_Docbook [7] http://l10n.kde.org/stats/doc/trunk-kde4/team/ -- Boudewijn Rempt http://www.valdyas.org, http://www.krita.org, http://www.boudewijnrempt.nl
Re: Using userbase for manuals
On Sunday 01 July 2012 Jul, Anne Wilson wrote: I'm not subscribed to this list, so please cc me in any replies. Sort of proves my point that Mirko is right and that we need a KDE-wide mailing list for all contributors. ... Boud - I'm not arguing, but is email notification essential? Maybe it is, but it's possible to craft an RSS/Atom feed for Recent Changes affecting your pages. Would that help? Oh, that would work as well. I get forum updates in akregator, and that's fine. I just need all changes to a certain project pushed to me, because I simply don't have the time to check manually what is changed. ... Something I'd really like to see is applications having links to UserBase and forum.kde.org (maybe to a specific sub-forum) in the Help menu. Perhaps that's what Christoph had in mind. Good point about the link to the forum. I definitely want that! -- Boudewijn Rempt http://www.valdyas.org, http://www.krita.org, http://www.boudewijnrempt.nl
Re: Using userbase for manuals
Hello, On Sunday 1 July 2012 08:02:28 Boudewijn Rempt wrote: I'm actually not sure kde-core-devel is the right list... But the e.V. mailing list certainly isn't, and we don't seem to have any place for discussions that affect KDE as a whole. Well, I think nowadays the name of kde-core-devel is confusing. The customs made its focus evolve over time, I think nowadays it's really the forum where the different KDE teams meet. It's really kde-townhall IMO. Anyway... I'm sidetracking a bit. :-) In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p5) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I think that would be a great improvement. The current way we deal with user documentation just doesn't scale. Trying to foster at this easier to contribute even from users documentation would help greatly with that. If we can get more user engagement that'd be a win for our community. I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days, the big thing is that it gets users right where they can fix the manual (Except on windows, where the browser invocation seems broken). I fully agree there. After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers... Thanks a lot for stepping up to bring up the matter. Highly appreciated. Regards. -- Kévin Ottens, http://ervin.ipsquad.net KDAB - proud patron of KDE, http://www.kdab.com signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
On Sunday 1 July 2012 09:21:08 Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt va escriure: I'm actually not sure kde-core-devel is the right list... But the e.V. mailing list certainly isn't, and we don't seem to have any place for discussions that affect KDE as a whole. In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p5) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. It's all very hypothetical isn't it? :-) More seriously, I think we shouldn't loose perspective here. Yes, you're right, it *can* happen, but Boudewijn is also right, it's becoming rare situation. My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. This way we'd still benefit from the better contribution scalability of userbase compared to our current situation. That'd make for a more complex solution on the client side though, that's why I wouldn't jump the gun on it immediately. Regards. -- Kévin Ottens, http://ervin.ipsquad.net KDAB - proud patron of KDE, http://www.kdab.com signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
On Sunday, July 01, 2012 09:21:08 AM Albert Astals Cid wrote: I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. I agree with you. Another situation is when traveling or when you are in a country with roaming phone connection. There might also be closed down network with KDE application, where you don't have full internet access. Andras
Re: Using userbase for manuals
El Diumenge, 1 de juliol de 2012, a les 09:49:11, Kevin Ottens va escriure: On Sunday 1 July 2012 09:21:08 Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt va escriure: I'm actually not sure kde-core-devel is the right list... But the e.V. mailing list certainly isn't, and we don't seem to have any place for discussions that affect KDE as a whole. In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p=125) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. It's all very hypothetical isn't it? :-) It's hypothetical because i did not want to use krita, but yes, i do not have internet connection in my room of the hostel. I do not have internet connection when i'm travelling in a train, or in a plane, or ... More seriously, I think we shouldn't loose perspective here. Yes, you're right, it *can* happen, but Boudewijn is also right, it's becoming rare situation. Sincerely I don't agree, having 100% internet connection each time I use my computer is something I don't have and I do live in Europe, I can't think what's like for someone in poorer regions. My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. This way we'd still benefit from the better contribution scalability of userbase compared to our current situation. And i'm going to be a pain here, but i do not agree userbase scale better either. Let's see Krita manual at http://userbase.kde.org/Krita it's translated to 7 languages only two of them being at 100% Now let's see KMail manual at http://l10n.kde.org/stats/doc/stable-kde4/po/kmail.po/ and we have 12 at 100% and a few more over 90% Cheers, Albert That'd make for a more complex solution on the client side though, that's why I wouldn't jump the gun on it immediately. Regards.
Re: Using userbase for manuals
Hi, Am Sonntag, 1. Juli 2012, 09:21:08 schrieb Albert Astals Cid: El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt va escriure: In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p=125) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. +1 There are lot of nice places on this planet where there is no (good or cheap) internet connection. Which is fine in one way (gives you a break without needing to find excuses :) ) but bad for dependency on on-line stuff. You preinstall most of your application as well, and do not apt-get them on- demand (modulo web apps), right? :) So at least being able to get snapshots of the stuff in userbase (as packages) would be really needed. Otherwise I agree. The strange duplication between userbase and manuals ideally finds an end in the near future, and with the current efforts on translation support another show stopper has been removed. Next on my wishlist would be a proper consistent structure on userbase, so documentation for different versions of a program is supported. After all there are usually versions of a program in use out there, and you do not want to disappoint those which can not update or do not want to update. Cheers Friedrich
Re: Using userbase for manuals
On 07/01/2012 07:02 AM, Boudewijn Rempt wrote: After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers... Over at Konversation we've likewise struggled to keep our Docbook manual going: It's still among the better ones around, but we've been terribly lazy and let it rot, and if it hadn't been for Burkhard Lück showing it some love last year, it'd would probably be too outdated to use by now. At the same time we're doing reasonably well at maintaining our Userbase presence. We used to have our own MediaWiki installation but migrated everything to Userbase last year, and I wrote some software that sends report mails to our development mailing list highlighting changes and new pages so we can review them and make sure the quality stays high. Newly written documentation is now usually added to the wiki, not the manual, e.g. I wrote this this month: http://userbase.kde.org/Konversation/Configuring_SASL_authentication I can't really put my finger on it, but somehow it's just more convenient and enoyable to do it in the wiki. It gets you easy preview, makes collaboration easier, and somehow it feels like a more appropriate place for topic-focused guides than the book- structured Docbook manual. At the same time topic-focussed guides seem to be the best fit for us, because being an IRC client our helpdesk naturally is the IRC channel and handing out links that answer a particular question comprehensively works very well there. Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. -- Best regards, Eike Hein
Re: Using userbase for manuals
On Sunday 01 July 2012 Jul, Eike Hein wrote: On 07/01/2012 07:02 AM, Boudewijn Rempt wrote: After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers... Over at Konversation we've likewise struggled to keep our Docbook manual going: It's still among the better ones around, but we've been terribly lazy and let it rot, and if it hadn't been for Burkhard Lück showing it some love last year, it'd would probably be too outdated to use by now. At the same time we're doing reasonably well at maintaining our Userbase presence. We used to have our own MediaWiki installation but migrated everything to Userbase last year, and I wrote some software that sends report mails to our development mailing list highlighting changes and new pages so we can review them and make sure the quality stays high. I want that! I _so_ want that, too! Newly written documentation is now usually added to the wiki, not the manual, e.g. I wrote this this month: http://userbase.kde.org/Konversation/Configuring_SASL_authentication I can't really put my finger on it, but somehow it's just more convenient and enoyable to do it in the wiki. It gets you easy preview, makes collaboration easier, and somehow it feels like a more appropriate place for topic-focused guides than the book- structured Docbook manual. At the same time topic-focussed guides seem to be the best fit for us, because being an IRC client our helpdesk naturally is the IRC channel and handing out links that answer a particular question comprehensively works very well there. Plus, the wiki allows lots of extra stuff, like embedded video, links and so on. Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. = -- Boudewijn Rempt http://www.valdyas.org, http://www.krita.org, http://www.boudewijnrempt.nl
Re: Using userbase for manuals
On Sunday 1 July 2012 10:17:21 Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 09:49:11, Kevin Ottens va escriure: More seriously, I think we shouldn't loose perspective here. Yes, you're right, it *can* happen, but Boudewijn is also right, it's becoming rare situation. Sincerely I don't agree, having 100% internet connection each time I use my computer is something I don't have and I do live in Europe, I can't think what's like for someone in poorer regions. Indeed, you got a point. My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. This way we'd still benefit from the better contribution scalability of userbase compared to our current situation. And i'm going to be a pain here, but i do not agree userbase scale better either. Let's see Krita manual at http://userbase.kde.org/Krita it's translated to 7 languages only two of them being at 100% Now let's see KMail manual at http://l10n.kde.org/stats/doc/stable-kde4/po/kmail.po/ and we have 12 at 100% and a few more over 90% Right but that said, the number of translations is not the only metric to take into account regarding documentation. Overall quality of it and its coverage of the application features, keeping up with changes, are equally important IMO. That's where I think the wiki is actually superior to the docbook stuff we're doing (as Boud and Eike pointed out). Now the low number of translations? That's likely in part because our translators are not used to look there to translate. Which raises the question of: If we were to consistently use the wiki how do we best support our documentation translators? Would they just be happy with being pointed to the wiki as it is a simple enough tool? Or would they need the wiki content extracted as po files so that they use their current toolchain for translation (aka the wiki is a too simple tool)? Both possibilities are fine IMO. Means in the second case we need to write an equivalent to our current docbook extractor but for the wiki somehow. Regards. -- Kévin Ottens, http://ervin.ipsquad.net KDAB - proud patron of KDE, http://www.kdab.com signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
On Sunday 01 July 2012 Jul, Kevin Ottens wrote: And i'm going to be a pain here, but i do not agree userbase scale better either. Let's see Krita manual at http://userbase.kde.org/Krita it's translated to 7 languages only two of them being at 100% Now let's see KMail manual at http://l10n.kde.org/stats/doc/stable-kde4/po/kmail.po/ and we have 12 at 100% and a few more over 90% Right but that said, the number of translations is not the only metric to take into account regarding documentation. Overall quality of it and its coverage of the application features, keeping up with changes, are equally important IMO. The krita manual also isn't an import of an existing docbook manual, we scrapped the old one completely -- in other words, it hasn't been around as long as the kmail manual. That's where I think the wiki is actually superior to the docbook stuff we're doing (as Boud and Eike pointed out). Now the low number of translations? That's likely in part because our translators are not used to look there to translate. Which raises the question of: If we were to consistently use the wiki how do we best support our documentation translators? Would they just be happy with being pointed to the wiki as it is a simple enough tool? Or would they need the wiki content extracted as po files so that they use their current toolchain for translation (aka the wiki is a too simple tool)? I can't answer to that, but the fact that the krita manual in its current stage already has so many translations is encouraging. Both possibilities are fine IMO. Means in the second case we need to write an equivalent to our current docbook extractor but for the wiki somehow. -- Boudewijn Rempt http://www.valdyas.org, http://www.krita.org, http://www.boudewijnrempt.nl
Re: Using userbase for manuals
On Sunday 01 July 2012 Jul, Boudewijn Rempt wrote: On Sunday 01 July 2012 Jul, Eike Hein wrote: On 07/01/2012 07:02 AM, Boudewijn Rempt wrote: After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers... Over at Konversation we've likewise struggled to keep our Docbook manual going: It's still among the better ones around, but we've been terribly lazy and let it rot, and if it hadn't been for Burkhard Lück showing it some love last year, it'd would probably be too outdated to use by now. At the same time we're doing reasonably well at maintaining our Userbase presence. We used to have our own MediaWiki installation but migrated everything to Userbase last year, and I wrote some software that sends report mails to our development mailing list highlighting changes and new pages so we can review them and make sure the quality stays high. I want that! I _so_ want that, too! I just got that :-). I'm very happy with it, but Eike is right that it probably wouldn't scale, being a poller. It's really something that needs to be fixed in the wiki system, so we can get a mail for every change to a manual done in the wiki. I'm just to dependent on getting all my updates in kmail... -- Boudewijn Rempt http://www.valdyas.org, http://www.krita.org, http://www.boudewijnrempt.nl
Re: Using userbase for manuals
2012/7/1 Eike Hein h...@kde.org: Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. I 100% agree with Eike. Albert is right, but in reality there're two things we need to consider 1) documentation maintainability development teams consistently fail to maintain documentation, so quality and completeness get hurt 2) user involvement for KDevelop the best documentation is usually written by users, userbase wikis are a better way to involve users than docbooks
Re: Using userbase for manuals
Hi, On Sunday, July 01, 2012 09:21:08 AM Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. Imo, having the docbook is not that bad. We even have tools (like the Kate plugin) helping to write it pretty much error-free out of the box. In Kate, we have some places where we have direct links to the handbook (by using anchors in the docbook). As example, look at how editing the modelines in the Open/Save dialog works: http://wstaw.org/m/2012/07/01/plasma-desktopYD4467.jpg Here, the help icon appears next to all items, and opens the docbook exactly at the correct location. In order to make this work, we need tight control over how the linked documentation looks like (the anchors need to be present). Currently, in Kate we are keeping the docbook pretty much up-to-date as we introduce changes to the code. I agree that it's (a lot of) work, but it can be done by strictly following this rule. I'm not convinved at all that a wiki provides us the control over all translations to keep the feature mentioned above... So I'm in favor of docbook, still... What about communication more that the documentation is part of the development process and it is a requirement to keep it up-to-date? Dominik
Re: Using userbase for manuals
On 07/01/2012 07:02 AM, Boudewijn Rempt wrote: After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers... Over at Konversation we've likewise struggled to keep our Docbook manual going: It's still among the better ones around, but we've been terribly lazy and let it rot, and if it hadn't been for Burkhard Lück showing it some love last year, it'd would probably be too outdated to use by now. At the same time we're doing reasonably well at maintaining our Userbase presence. We used to have our own MediaWiki installation but migrated everything to Userbase last year, and I wrote some software that sends report mails to our development mailing list highlighting changes and new pages so we can review them and make sure the quality stays high. Newly written documentation is now usually added to the wiki, not the manual, e.g. I wrote this this month: http://userbase.kde.org/Konversation/Configuring_SASL_authentication I can't really put my finger on it, but somehow it's just more convenient and enoyable to do it in the wiki. It gets you easy preview, makes collaboration easier, and somehow it feels like a more appropriate place for topic-focused guides than the book- structured Docbook manual. At the same time topic-focussed guides seem to be the best fit for us, because being an IRC client our helpdesk naturally is the IRC channel and handing out links that answer a particular question comprehensively works very well there. Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. +1 for that, but only if it is an extension to the current manuals. For example for Kate, Hollingsworth and Lück did a really GREAT job to write a consistent manual. And like programming, manual writing is nothing arbitrary people can do. Its an art on its own and I doubt we would have the same quality if arbitrary users just write up their knowledge. I think an additional standardized point of contact in the wiki would be great, just like hitting Help... hit Support Base... or what ever and get there the community info that are available for the application. There can be cool stuff, useful FAQ, howtos, video guides, whatever, but I think that should be in the normal case an extension of the local manual. Greetings Christoph -- -- Christoph Cullmann - AbsInt Angewandte Informatik GmbH Email: cullm...@absint.com Science Park 1 Tel: +49-681-38360-22 66123 Saarbrücken Fax: +49-681-38360-20 GERMANYWWW: http://www.AbsInt.com Geschäftsführung: Dr.-Ing. Christian Ferdinand Eingetragen im Handelsregister des Amtsgerichts Saarbrücken, HRB 11234
Re: Using userbase for manuals
On 07/01/2012 01:35 PM, Boudewijn Rempt wrote: I just got that :-). I'm very happy with it, but Eike is right that it probably wouldn't scale, being a poller. It's really something that needs to be fixed in the wiki system, so we can get a mail for every change to a manual done in the wiki. I'm just to dependent on getting all my updates in kmail... I initialy tried to make it not a poller, hoping that MediaWiki would be able to send me emails on changes, and then report generator would be a little daemon drinking from an IMAP inbox. However, ultimately it turned out to be impossible to get the right sort of emails from MediaWiki (namely one for every new page or page change under a cer- tain prefix), so I had to resort to polling via the API. -- Best regards, Eike Hein
Re: Using userbase for manuals
Am Sonntag, 1. Juli 2012, 13:14:19 schrieb Kevin Ottens: On Sunday 1 July 2012 10:17:21 Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 09:49:11, Kevin Ottens va escriure: More seriously, I think we shouldn't loose perspective here. Yes, you're right, it *can* happen, but Boudewijn is also right, it's becoming rare situation. Sincerely I don't agree, having 100% internet connection each time I use my computer is something I don't have and I do live in Europe, I can't think what's like for someone in poorer regions. Indeed, you got a point. My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. This way we'd still benefit from the better contribution scalability of userbase compared to our current situation. And i'm going to be a pain here, but i do not agree userbase scale better either. Let's see Krita manual at http://userbase.kde.org/Krita it's translated to 7 languages only two of them being at 100% Now let's see KMail manual at http://l10n.kde.org/stats/doc/stable-kde4/po/kmail.po/ and we have 12 at 100% and a few more over 90% Right but that said, the number of translations is not the only metric to take into account regarding documentation. Overall quality of it and its coverage of the application features, keeping up with changes, are equally important IMO. That's where I think the wiki is actually superior to the docbook stuff we're doing (as Boud and Eike pointed out). My experience translating docbooks extracted from userbase pages (which can be done via script in a minute) is slightly different. I have never finished a translation whithout fixing wrong/outdated stuff in the english documentation. Now the low number of translations? That's likely in part because our translators are not used to look there to translate. Which raises the question of: If we were to consistently use the wiki how do we best support our documentation translators? Would they just be happy with being pointed to the wiki as it is a simple enough tool? No, lokalize is a specialized translation tool with features like shortcuts to copy markup, a translation memory, a glossary etc. All these features are missing translating in the wiki. And in the wiki I can not change all german translations of foo from bar to baz using tools with an editor highligting foo, bar and baz in different colors like: $ python checkwordtranslation.py Usage:python checkwordtranslation.py [OPTION] /path/to/pofiledir/ arg1 [arg2 [arg3]] arg1 regexpression of english word in msgid arg2 list of regexpr with default translations of arg1, separated by , arg3 list of regexpr with wrong translations of arg1, separated by , quote args to use spaces ( ) in regexpressions Options: -h, --help : usage -s, --summary: print only summary -a, --all: print list of all messages, default print only list of messages with different translation -k, --konsole: only output to konsole, no edit dialog -m, --msglen int : check only msgids with lenmsglen characters, default no limit -w, --words int : check only msgids less the int words, default no limit -t, --translated : check only translated messages, default all messages. If word-lang!=, always true Output : print messages with arg1 msgid [and arg2 in msgstr] for msgids 80 characters or 10 words if arg2 (regexpr of default translations) !=, a dialog appears to edit all messages with different translation of arg1 use the script only with arg1 to pick up the different translations of arg1 from the konsole output then use it with arg1 / arg2 / arg3 to find all messages with different translation and edit them Or would they need the wiki content extracted as po files so that they use their current toolchain for translation (aka the wiki is a too simple tool)? Yes Both possibilities are fine IMO. Means in the second case we need to write an equivalent to our current docbook extractor but for the wiki somehow. -- Burkhard Lück
Re: Using userbase for manuals
написане Sun, 01 Jul 2012 10:49:11 +0300, Kevin Ottens er...@kde.org: On Sunday 1 July 2012 09:21:08 Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt va escriure: I'm actually not sure kde-core-devel is the right list... But the e.V. mailing list certainly isn't, and we don't seem to have any place for discussions that affect KDE as a whole. In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p=125) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. It's all very hypothetical isn't it? :-) More seriously, I think we shouldn't loose perspective here. Yes, you're right, it *can* happen, but Boudewijn is also right, it's becoming rare situation. My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. This way we'd still benefit from the better contribution scalability of userbase compared to our current situation. That'd make for a more complex solution on the client side though, that's why I wouldn't jump the gun on it immediately. Regards. Hi, Just a minor remarks on using UserBase for documentation. 1. It does not matter where you *do not* write your documentation. New Krita manual was started 5-01-2010 [1]. For now, it is not ready even at 1/10 level. The activity is extremely low. The content is badly formatted and hardly useful. The projection can be made (by exploring similar wiki documentation projects, like Fedora, openSUSE, Mandriva, and Debian/Ubuntu) that when it will be ready it becomes obsolete for the current version. Example of the manual that once was written and now partially outdated is Amarok Manual [2]. 2. Simple conversion docbook to wiki does not make manual useful. Example: Kexi handbook [3] was roughly converted to wiki with broken formatting, lost of index, and no substantial changes. Thanks to Burkhard it was polished (as a docbook) and converted back thanks to Claus Christensen. 3. Manuals can live without wiki conversion. Examples: Calligra Stage [4] and Calligra Sheets [5] manuals were never converted to wiki. For whatever reason, they are now in much more helpful state than Words and Krita docs (not saying that they have offline versions). 4. Proper formatting allows very easy conversion from wiki XML to docbook. Once well-formatted, wiki pages can be converted into offline form (docbook, PDF, or EPUB) in almost no time[6]. Examples: Amarok, Kexi, Kdenlive, KrossWordPuzzle, part of KMail offline manuals are converted (and slightly fixed) UserBase manuals. Just for curiosity, you can compare the level of the translation covering for these docs in kde-i18n Subversion [7] and on UserBase. Conclusion I know that it is hard for developers to keep backward compatibility. But please do not cease to maintain DocBook compatibility in KDE 5. If you do, you will likely lost most of your docs and most of your documentation translators. I am far from making decision for developers, but it is always good to have some plan with real results. Just moving docs in hope that after that someone definitely write them is counterproductive. Just my 2 cents. Best regards, Yuri KDE Ukrainian team coordinator [1] http://userbase.kde.org/User:Boudewijn/Krita/Manual [2] http://userbase.kde.org/Amarok/Manual [3] http://userbase.kde.org/Kexi/Handbook [4] http://docs.kde.org/development/en/calligra/stage/index.html [5] http://docs.kde.org/development/en/calligra/sheets/index.html [6] http://userbase.kde.org/How_To_Convert_a_UserBase_Manual_to_Docbook [7] http://l10n.kde.org/stats/doc/trunk-kde4/team/
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 01.07.2012 13:14, schrieb Kevin Ottens: On Sunday 1 July 2012 10:17:21 Albert Astals Cid wrote: El Diumenge, 1 de juliol de 2012, a les 09:49:11, Kevin Ottens va escriure: More seriously, I think we shouldn't loose perspective here. Yes, you're right, it *can* happen, but Boudewijn is also right, it's becoming rare situation. Sincerely I don't agree, having 100% internet connection each time I use my computer is something I don't have and I do live in Europe, I can't think what's like for someone in poorer regions. Indeed, you got a point. My opinion is that I would love to go for it, and if over time that turns out to be a problem, we could ship a dump of the relevant wiki content along the application. It'd be used as fallback if the wiki cannot be reached online. This way we'd still benefit from the better contribution scalability of userbase compared to our current situation. And i'm going to be a pain here, but i do not agree userbase scale better either. Let's see Krita manual at http://userbase.kde.org/Krita it's translated to 7 languages only two of them being at 100% Now let's see KMail manual at http://l10n.kde.org/stats/doc/stable-kde4/po/kmail.po/ and we have 12 at 100% and a few more over 90% Right but that said, the number of translations is not the only metric to take into account regarding documentation. Overall quality of it and its coverage of the application features, keeping up with changes, are equally important IMO. That's where I think the wiki is actually superior to the docbook stuff we're doing (as Boud and Eike pointed out). Now the low number of translations? That's likely in part because our translators are not used to look there to translate. Which raises the question of: If we were to consistently use the wiki how do we best support our documentation translators? Would they just be happy with being pointed to the wiki as it is a simple enough tool? Or would they need the wiki content extracted as po files so that they use their current toolchain for translation (aka the wiki is a too simple tool)? Both possibilities are fine IMO. Means in the second case we need to write an equivalent to our current docbook extractor but for the wiki somehow. Actually no need to. Translations can already be exported/imported as po files. One of the benefits of the translate extension (which was highlighted today in a talk at akademy ;) And docbook export is also something that is being tested. It is not 100% save yet, just needs a bit more eyes to really make it work good. The only issue is probably about workflow and some improvements in the produced output, but the authors of that mediawiki extension are indeed very responsive. Regards. Cheerio, - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/wR3cACgkQgFDgF4YW7sf7JACgtT4M3n1uCyI53Y1ArWic/2NH Jl0AnRuDEhvJ9ZOsXpIkDe9PVNCkykV1 =pWHN -END PGP SIGNATURE-
Re: Using userbase for manuals
El Diumenge, 1 de juliol de 2012, a les 14:37:44, Alexander Dymo va escriure: 2012/7/1 Eike Hein h...@kde.org: Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. I 100% agree with Eike. Albert is right, but in reality there're two things we need to consider 1) documentation maintainability development teams consistently fail to maintain documentation, so quality and completeness get hurt That's why we have an amazing documentation team at kde-doc-engl...@kde.org They will be happy writting/updating your documentation, you only need to tell them where and what needs work and you'll get a new and shiny docbook I just got the Okular one updated by them and I didn't even answer for it :-) 2) user involvement for KDevelop the best documentation is usually written by users, userbase wikis are a better way to involve users than docbooks I don't agree with that, users are good writting tips for eachother but not necessarily good at organizing the content in a coherent and sensible way. Cheers, Albert
Re: Using userbase for manuals
On Sunday 1 July 2012 14:49:59 Ingo Malchow wrote: Actually no need to. Translations can already be exported/imported as po files. One of the benefits of the translate extension (which was highlighted today in a talk at akademy ;) And docbook export is also something that is being tested. It is not 100% save yet, just needs a bit more eyes to really make it work good. The only issue is probably about workflow and some improvements in the produced output, but the authors of that mediawiki extension are indeed very responsive. Excellent! I love how you are already a step ahead to fulfill our needs. Regards. -- Kévin Ottens, http://ervin.ipsquad.net KDAB - proud patron of KDE, http://www.kdab.com signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 I'm not subscribed to this list, so please cc me in any replies. This thread was pointed out to me, and I'd like to comment on some of the points raised. Off-line documentation - There is an extension, Collections, which allows users to select pages from UserBase (TechBase too, if it's relevant) that are useful at that time - usually when you are learning a new application. They can be renedered as html or as a pdf, and saved to HDD or pen-drive, for carrying around. With today's inexpensive rewritable USB gadgets this means you can keep things up to date easily, without having to burn disks etc.. At the same time, the Collection facility could be used to produce disks for off-line use - but looking at the speed that things change, that may not be a good solution. Taking with me an own-language set of pages for that shiny new application does sound extremely useful to me. The extension has been tested on our sandbox, and basically it is working. Initially we used a public rendering server, but our sysadmins tell me that we can now render on our own server, which helps a lot, both for speed and reliability. As usual, man-power and time restraints are the only things holding us back. Going on to Kevin Ottens' point about docbook and docbook translators - - I think that time will show where the strong points of wiki documentation and docbook documentation lie - probably they will best address different needs, but at this moment it's too early to tell. As for the translators themselves, I'm told that they will not like working inside a browser - something that is essential to this method. However, there is a MediaWiki API that can allow gettext directly - I'm just not qualified to discuss it. Anyone interested might be advised to try #kde-www or ##mediawiki as a possible source of help. The current situation is that, using a browser and the normal Translate interface, it is possible to export to Gettext, and easy to re-import the messages. Boud - I'm not arguing, but is email notification essential? Maybe it is, but it's possible to craft an RSS/Atom feed for Recent Changes affecting your pages. Would that help? Maintainability is definitely where wiki scores. The original pages for an application really should be written by a developer or someone closely working with the developers, but fleshing out with user experience can make a huge difference. And since translators usually use Special:LanguageStats/your-language-code they can see at a glance which pages have changed, and to what degree. Eike - there is a Special:RecentChangesLinked - have you explored the possibility of that working for you? Burkhard's comment about always needing to fix outdated or wrong information on the English page is important, but true of pretty well any system. I think it is fair to say that most people are happiest using the tools that they are familiar with. We have several translators on UserBase that export the English page then work in Lokalize so that they have those additional tools. I'd like to draw your attention, too, to Yurchor's excellent documetation http://userbase.kde.org/How_To_Convert_a_UserBase_Manual_to_Docbook Basically, as Ingo has said, we need feedback. Tell us what you need and, together with Niklas, we will do our level best to give you it. :-) Something I'd really like to see is applications having links to UserBase and forum.kde.org (maybe to a specific sub-forum) in the Help menu. Perhaps that's what Christoph had in mind. Anne -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.12 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/wUJIACgkQj93fyh4cnBdtlACff3AVV/o4jN6WFc4/0jfeMuM7 7jYAn22h6ko6cSWT+3JmC5Qwq4hNX5Hk =RvZg -END PGP SIGNATURE-
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 01.07.2012 15:33, schrieb Albert Astals Cid: El Diumenge, 1 de juliol de 2012, a les 14:37:44, Alexander Dymo va escriure: 2012/7/1 Eike Hein h...@kde.org: Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. I 100% agree with Eike. Albert is right, but in reality there're two things we need to consider 1) documentation maintainability development teams consistently fail to maintain documentation, so quality and completeness get hurt That's why we have an amazing documentation team at kde-doc-engl...@kde.org They will be happy writting/updating your documentation, you only need to tell them where and what needs work and you'll get a new and shiny docbook I just got the Okular one updated by them and I didn't even answer for it :-) 2) user involvement for KDevelop the best documentation is usually written by users, userbase wikis are a better way to involve users than docbooks I don't agree with that, users are good writting tips for eachother but not necessarily good at organizing the content in a coherent and sensible way. I don't think it boils down to have either the one way or the other, but how to combine both of them. Use help of users and simplify the way of contribution and on the other hand provide a coherent and sensible way to produce nice documentation which is even up to date. Cheers, Albert - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/wY7QACgkQgFDgF4YW7seoIwCgmT1flD4KOJkd90FHixD9+83m UXQAn0gAtnCPCGyrH+oDaLTon/XzBCy0 =jzF8 -END PGP SIGNATURE-
Re: Using userbase for manuals
On 07/01/2012 03:28 PM, Anne Wilson wrote: Eike - there is a Special:RecentChangesLinked - have you explored the possibility of that working for you? Visiting a page == polling. -- Best regards, Eike Hein
Re: Using userbase for manuals
(Many things have been already pointed out, but I'll repeat, to hopefully frame it a bit more concretely.) The way I see it, there are really three conceptually independent aspects here: 1) Documentation should be up to date, promtly reacting to changes in program features and behavior. 2) Documentation should be translatable in a way that maximizes the amount and quality of translation. 3) Documentation should be readily available to users. For (3), of course it would be nice if the users should have documentation in conditions of low connectivity, but also in formats other than a web page. Someone should simply make this technically possible per the way (1) is done, with the scope as wide as desired. One bonus is integration into desktop environment's help viewer, such as KHelpCenter. (However, consider that maybe not all ways of (1) are good enough for true online documentation, i.e. what people called on-line before the web: when you are working in a program and want to invoke help for a particular section of it in which you are currently.) For (2), by now it has been amply demonstrated in practice that the translation should take place over PO files, which are automatically put into and taken from the KDE translation repository. While noone ever seriously suggested that another workflow can bring higher quality of translation, some people did hope that other workflows could at least bring higher amount of translation. But the reality is that a dedicated translator using dedicated translation tools is an order of magnitude more productive than a drive-by wiki contributor, and that hoped for swaths of drive-by wiki contributors never materialized. So, regardless of how (1) is done, as long as there is an automatic turn-around of PO files in KDE translation repository, (2) is covered. Someone should simply make this technically possible per the way (1) is done. (If documentation is written in a really fluid manner, one should also think about freezes, if possible.) Now (1), that is the most interesting bit from my viewpoint. The nice thing about (1) is that I see no reason why everyone should do it in the same way, as long as means for (2) and (3) are (in process of being) established for given (1). I personally think that to have serious reference documentation, a dedicated documentation author is necessary, and that wikis, for example, can only impede that person's work; wikis *may* be suitable for tips and tricks or how to do X loosely connected texts, but reference documentation is another thing entirely. Maybe some programs do not need reference documentation at all? That's fine by me, and I'd drop the current policy that all KDE SC programs should have it. But, when program authors do decide that they want to have reference documentation, I don't see how any workflow can be technically more suitable (easier to write, easier to maintain) than the documentation source files residing right with the code, in the program's repository. To separate documentation from the code repository, in my view, automatically states we don't need/won't write reference documentation. What I'm not claiming is that documentation sources must be Docbook, and I suspect that Docbook is what's driving many people away from maintaining documentation in this way. I would encourage people to look into other documentation formats, providing that they always consider (2) (do we have a format-X to PO and back converter? how will we hook it into KDE translation repository automation?). [: Eike Hein :] [...] but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. [...] _From my viewpoint, that which is on Konversation wiki is not reference documentation, which you too implied in the preceding text; and not having reference is completely fine by me, as I mentioned above. Even so, how comes this existing content on the wiki is easier to maintain than that same content would be in offline, i.e. within-repository form? For example, if you modify some feature, how does wiki make it easier to detect that documentation change is needed and to perform that change, than it would be the case with within-repository documentation? Could it be that you are simply driven away by the Docbook's towering hulk? :) Maybe people who actually do want to write and maintain documentation for their programs, but not linear-flow reference documentation, should look at Mallard[1] (and look at achieving (3) and (2) for it in context of KDE, the PO convertor being already available). It is again XML, but with very small set of basic tags (easily fits into one person's head), and it was created explicitly for writing topic-oriented documentation. [1] http://projectmallard.org/about/index.html -- Chusslove Illich (Часлав Илић) signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
On 07/01/2012 05:45 PM, Chusslove Illich wrote: _From my viewpoint, that which is on Konversation wiki is not reference documentation, which you too implied in the preceding text; and not having reference is completely fine by me, as I mentioned above. Even so, how comes this existing content on the wiki is easier to maintain than that same content would be in offline, i.e. within-repository form? For example, if you modify some feature, how does wiki make it easier to detect that documentation change is needed and to perform that change, than it would be the case with within-repository documentation? Could it be that you are simply driven away by the Docbook's towering hulk? :) Yes - that's basically what I alluded to re gives you easy preview. -- Best regards, Eike Hein
Re: Using userbase for manuals
[: Chusslove Illich :] [...] Could it be that you are simply driven away by the Docbook's towering hulk? :) [: Eike Hein :] Yes - that's basically what I alluded to re gives you easy preview. Right, so there are a few ways to think about this. One is that even wanting a preview when using Docbook is a sort of workflow error :) (When I write Docbook, I never take previews while writing.) Another is that a simple tool is missing (or maybe not missing, I don't know) to show you the rendering when you execute it with Docbook file as argument. For example, coming back to that Mallard format I mentioned, here is what they have to say about preview: [: Mallard Ten Minute Tour :] [...] You can view this document by calling yelp from the command line and passing it the full path to the directory containing the page files. For example, if you have placed index.page in /home/drake/mydocument/, enter this at the command line: yelp /home/drake/mydocument/ (from http://projectmallard.org/about/learn/tenminutes.html). It works also when you give it a particular Mallard file, even if it is not the master file. I can't imagine it easier than this. Not to mention it needs no communication with the server, and could be easily invoked from whatever editor. -- Chusslove Illich (Часлав Илић) signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
Am 01.07.2012 17:45, schrieb Chusslove Illich: But, when program authors do decide that they want to have reference documentation, I don't see how any workflow can be technically more suitable (easier to write, easier to maintain) than the documentation source files residing right with the code, in the program's repository. which is not the case. To be honest I have no idea where to find the documentation of kwin, but I know it's not in our source code directory. On the other hand, I know where the documentation is in the wiki - google finds it ;-) What I'm not claiming is that documentation sources must be Docbook, and I suspect that Docbook is what's driving many people away from maintaining documentation in this way. Yeah, I think you are quite right with that assumption. Even if I knew where to find KWin documentation, I would not touch it due to the fact that it's docbook (tried it once, decided again that xml is just a form of binary and I don't write binary). Using Wiki markup is much more natural and with future MediaWiki releases we will even have WYSIWYG editors. Cheers Martin Gräßlin
Re: Using userbase for manuals
Am Sonntag, 1. Juli 2012, 20:33:26 schrieb Martin Gräßlin: Am 01.07.2012 17:45, schrieb Chusslove Illich: But, when program authors do decide that they want to have reference documentation, I don't see how any workflow can be technically more suitable (easier to write, easier to maintain) than the documentation source files residing right with the code, in the program's repository. which is not the case. To be honest I have no idea where to find the documentation of kwin, but I know it's not in our source code directory. kdebase/kde-workspace/doc/kcontrol/window* kdebase/kde-workspace/doc/kcontrol/kwin* On the other hand, I know where the documentation is in the wiki - google finds it ;-) What I'm not claiming is that documentation sources must be Docbook, and I suspect that Docbook is what's driving many people away from maintaining documentation in this way. Yeah, I think you are quite right with that assumption. Even if I knew where to find KWin documentation, I would not touch it due to the fact that it's docbook (tried it once, decided again that xml is just a form of binary and I don't write binary). That's really crazy, I can't write a simple one-liner code patch without getting compile errors, but similar to Yuri I found it easy to write docbook markup. -- Burkhard Lück
Re: Using userbase for manuals
[: Burkhard Lück :] That's really crazy [...] similar to Yuri I found it easy to write docbook markup. While to me Docbook is simply less bad than other things, so I use Docbook when I want to document something about software (if I didn't need HTML pages, I'd use Latex instead). And when Martin says we will even have WYSIWYG editors [for wiki editing], my skin starts crawling, yet he is looking forward to it. The point is, different people like different things. I argue that it is of outer importance that the documentation writer uses the writing *concept* suitable to own taste (WYSIWYG vs. WYSIWYM, markup type, etc.), and only within that writing concept, look for particular formats and workflows. I further argue that, if people who are accustomed to version control find web-something-thingy (such as wiki) optimal for their documentation writing workflow, something has gone horribly wrong; and that efficiency of writing and maintenance, as well as documentation availability, will suffer because of it. Instead, they should keep documentation tight to their sources, and in format which best fits their writing concept. For example, there certainly exist wiki-like offline markups that can be converted to HTML pages (e.g. Markdown). I think we should encourage people to experiment in this direction, rather than press learn Docbook. -- Chusslove Illich (Часлав Илић) signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
On Sunday, 1. July 2012 10:22:41 Friedrich W. H. Kossebau wrote: Hi, Am Sonntag, 1. Juli 2012, 09:21:08 schrieb Albert Astals Cid: El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt va escriure: In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p=125) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days I disagree, as a matter of fact, I don't have internet connection in the room in my hostel, so if i had a need to use krita I'd need to read its manual (since my painting/drawing skills are null) and i'd be not happy to discover I can't read the manual. +1 There are lot of nice places on this planet where there is no (good or cheap) internet connection. Which is fine in one way (gives you a break without needing to find excuses :) ) but bad for dependency on on-line stuff. well, I more or less never use the user manuals. If they were online in a wiki, I suspect they might be more complete and more current. So, I'm for making it online. And then this strange help application wouldn't pop up, but just a browser... Alex
Re: Using userbase for manuals
Am Sonntag, 1. Juli 2012, 21:56:16 schrieb Chusslove Illich: [: Burkhard Lück :] That's really crazy [...] similar to Yuri I found it easy to write docbook markup. While to me Docbook is simply less bad than other things, so I use Docbook when I want to document something about software (if I didn't need HTML pages, I'd use Latex instead). And when Martin says we will even have WYSIWYG editors [for wiki editing], my skin starts crawling, yet he is looking forward to it. The point is, different people like different things. Sure, everyone should use his favorite tool to do things. But what I really don't understand, why a devel writing C/C++ code says xml is just a form of binary. The syntax rules of docbook are some magnitudes simpler than the syntax rules of C/C++ code. -- Burkhard Lück
Re: Using userbase for manuals
[: Burkhard Lück :] But what I really don't understand, why a devel writing C/C++ code says xml is just a form of binary. Hey, some devel writing Lisp code say C++ is just a form of binary. Doesn't really matter why. -- Chusslove Illich (Часлав Илић) signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 01.07.2012 21:56, schrieb Chusslove Illich: [: Burkhard Lück :] That's really crazy [...] similar to Yuri I found it easy to write docbook markup. While to me Docbook is simply less bad than other things, so I use Docbook when I want to document something about software (if I didn't need HTML pages, I'd use Latex instead). And when Martin says we will even have WYSIWYG editors [for wiki editing], my skin starts crawling, yet he is looking forward to it. The point is, different people like different things. I argue that it is of outer importance that the documentation writer uses the writing *concept* suitable to own taste (WYSIWYG vs. WYSIWYM, markup type, etc.), and only within that writing concept, look for particular formats and workflows. I further argue that, if people who are accustomed to version control find web-something-thingy (such as wiki) optimal for their documentation writing workflow, something has gone horribly wrong; Sorry, not sure i get you here. Do you mean a certain location for version control? Because, wikis provide version control since the beginning, and you can roll back to any point if you wish. and that efficiency of writing and maintenance, as well as documentation availability, will suffer because of it. Instead, they should keep documentation tight to their sources, and in format which best fits their writing concept. For example, there certainly exist wiki-like offline markups that can be converted to HTML pages (e.g. Markdown). I think we should encourage people to experiment in this direction, rather than press learn Docbook. - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/wsm4ACgkQgFDgF4YW7seBJgCglaZJacJJ+PQwm84pKJxatB5O ocsAoMYs4u7gJoDxyofbrFYga2T0fgVj =10Vm -END PGP SIGNATURE-
Re: Using userbase for manuals
On 07/01/2012 09:56 PM, Chusslove Illich wrote: I further argue that, if people who are accustomed to version control find web-something-thingy (such as wiki) optimal for their documentation writing workflow, something has gone horribly wrong; and that efficiency of writing and maintenance, as well as documentation availability, will suffer because of it. Instead, they should keep documentation tight to their sources, and in format which best fits their writing concept. For example, there certainly exist wiki-like offline markups that can be converted to HTML pages (e.g. Markdown). I think we should encourage people to experiment in this direction, rather than press learn Docbook. I use asciidoc in another project which can be converted to Docbook and is really nice: http://www.methods.co.nz/asciidoc/ -- Best regards, Eike Hein
Re: Using userbase for manuals
[: Chusslove Illich :] I further argue that, if people who are accustomed to version control find web-something-thingy (such as wiki) optimal for their documentation writing workflow, something has gone horribly wrong; [: Ingo Malchow :] Sorry, not sure i get you here. Do you mean a certain location for version control? Because, wikis provide version control since the beginning, and you can roll back to any point if you wish. I mean: different location, different VCS, over-the-web interaction with it, over-the-web source processing (i.e. previewing, since nothing else is possible), and maybe even in-browser editing (though I can avoid at least that part, copy first to a proper editor). Doesn't something seem the slightest bit wrong here to you? -- Chusslove Illich (Часлав Илић) signature.asc Description: This is a digitally signed message part.
Re: Using userbase for manuals
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 01.07.2012 23:19, schrieb Chusslove Illich: [: Chusslove Illich :] I further argue that, if people who are accustomed to version control find web-something-thingy (such as wiki) optimal for their documentation writing workflow, something has gone horribly wrong; [: Ingo Malchow :] Sorry, not sure i get you here. Do you mean a certain location for version control? Because, wikis provide version control since the beginning, and you can roll back to any point if you wish. I mean: different location, different VCS, over-the-web interaction with it, over-the-web source processing (i.e. previewing, since nothing else is possible), and maybe even in-browser editing (though I can avoid at least that part, copy first to a proper editor). Doesn't something seem the slightest bit wrong here to you? Ok. then i got it right :D But wrong, hmmm, no. Open source culture is all about diversity. And it needs to be dealt with. Of course, one person prefers to edit docbook, the other prefers wiki. One considers xml as binary data, the other thinks xml is not geeky enough, etc... But what really matters is, how can we improve the integration of all those aspects. Like i said in a different mail, it is not about either using one or the other, but maybe trying to improve the collaboration or even merge of the existing solutions. I prefer Scrubs over Friends, but that doesn't make me an enemy of the Friends episodes. The webteam tries to integrate a better water carrier job since quite some time now, with not that much success overall. And believe me, we are open to anything. Stating wiki markup is not what i like is not helpful. Stating what you would need is more helpful. The markup is not a question, as i assume any dev should easily be able to adapt. Cheerio, - -- Ingo Malchow (neverendingo) -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.18 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAk/wyUcACgkQgFDgF4YW7senXwCeJLqigBa3zEiqSO7a4Rrnm+aT WwAAoIHVUD3eM4eYeSmGWcqna8WPudTZ =dXUR -END PGP SIGNATURE-
Re: Using userbase for manuals
On Sunday, July 01, 2012 07:02:28 Boudewijn Rempt wrote: I'm actually not sure kde-core-devel is the right list... But the e.V. mailing list certainly isn't, and we don't seem to have any place for discussions that affect KDE as a whole. In any case, Ingo Malchow said in his blog (http://blog.neverendingo.de/?p=125) We have a great userbase.kde.org but developers don’t use it that much, nor is there any links from applications towards Userbase. Well, actually we have. I replaced the offline help documentation in Krita with a link to the manual on userbase. I have done this for two reasons: * I couldn't maintain the offline manual anyway after the change to 2.0 * this way the user gets sent right to the place where they can contribute to the manual (and I've got users contributing to it now) I'm not concerned that users cannot access the help when they are off-line. That's a vanishingly rare situation these days, the big thing is that it gets users right where they can fix the manual (Except on windows, where the browser invocation seems broken). After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers... Instead of writing small snippets here and there in the discussion, I'll collect my thoughts in this mail. I think we are missing something here: I'ts not about the tools. It's about the format. (and to some extent the placement of the documentation (near the code or centrally)). If we can just agree on a format for our documentation then the question of tools is irrelevant. Anybody can use their own tool for editing the content and I think we can set up a default tool chain for maintaining it, translations and transforming it to something suitable for viewing. The default used to be and still is docbook, residing in the source tree in the source repository. Advantages: 1. The documentation is close to the source and it's easy to update it even during the development phases. True, this didn't happen very often but the potential was there. 2. Versioning of the documentation follows the software. 3. Easy to publish at the same time as the software is published. Disadvantages: 1. Some people (especially some good writers?) are uncomfortable with source revision systems, especially git. 2. Some people (especially some good writers?) are uncomfortable with markup languages and prefer wysiwyg? I'm not sure but I have the feeling that even if we have some awesome doc writers that love docbook I believe that others are put off by it. 3. The documentation is somewhat hidden for potential writers due to 1. above. Now, the suggestion was to move to a wiki instead Advantages: 1. Easier to find the documentation for potential writers. 2. (Supposedly) easier to edit [Personally I'm not sure that editing advanced wiki markup is easier than docbook] Disadvantages: 1. Difficult to maintain different versions of the documentation for different versions of the software. 2. Users need to be online to view the documentation. I think that calling this problem vanishingly rare is a very northern Europe centric view. And even I who have excellent broadband often still do work offline sometimes. 3. Translations(?) Unfortunately I missed the Akademy presentation on multi- language wikis but I understand that this is indeed a problem. I suppose that we could find or create tools to pull the wiki contents and create the current binary format for offline viewing. What I would like to see is a discussion on what the writers and potential writers want to use (tools and formats) and how we as developers can provide them with the best toolchain. And here's a radical suggestion: How about using ODT as the documentation format? It is a powerful format, there are some very good tools to edit that (one of them just got the Akademy award), there is change tracking features to keep track of edits and reviews. There are also excellent viewers for it. For translations, there is even an experimental tool for Calligra words that sends a selection of text to Google translate and gives you an automatic translation back.
