Documentation Wish List

From Mandriva Community Wiki

• For modern Kernel (2.6.2x) a good Documentation over ISDN-> allover in the Internet ar old unusable doc´s, users with ISDN living (most) in little Villages, no chance for DSL

• Integrate Official Mandriva Linux documentation into khelpcenter & yelp for easy browsing and searching

• Center all images in PDF pages

• Special text like the one enclosed in <guilabel> and <application> tags should be rendered differently from normal text in DrakX-Help, too, maybe by hardcoding styles in HTML, as the installation inline help cannot use CSS.

• Make SVNNav sub-pages directly accessible, e.g [1], without the need to start browsing from the root each time.

Organization for translators (and other contributors):

When time comes to start translations, a complete and clear description of the documentation system and all needed indications must be sent to all contributors (writers, reviewers, translators...), to let them work easier and with less problems due to misunderstandings. These info must be kept current while the project evolves, and should include:

• what documents are needed in each language;
• what files are to be translated/updated for each language;
• how to read any report tables which might be showing useful info, including the ones above;
• in case part of the work will be paid, which part is it and how much will be paid;
• expected deadline;
• how does the system work:

• what happens when you commit a file to svn;
• how often are the various status/report/output pages updated;
• what do those status/report pages show (e.g. what is the "Status" column based upon? What differences are shown by the diffs?);
• how do translators know when a file is ready to be translated;

• how should contributors behave when editing English files;

suggestion: increment revision attribute - or add it if it doesn't exist yet, also adding a unique id if it's missing - for the tag whose contents you are updating (e.g. <para>, <imagedata>, etc.), EVERY TIME you edit anything, except maybe for very very minor edits like correcting typos or fixing English language with no effect on other languages; if in doubt, please do it! The old habit of letting people decide did not work and forced translators to much useless extra work. People must be told that the rule is always increase the revision and that they are allowed to skip this step only in rare exceptions. Translators prefer to have some more paragraphs to check, rather than having to check everything from scratch because revisions might not have been updated where it was needed instead.

• what infos must be included at the beginning of XML files: as of 2008.1, some files had lots of namespace declarations, others had less, some had the xml:lang attribute, some others had not...
• If possible, give hints for validating XML files with editors other than Emacs.

Remove all outdated docs about the documentation project, to prevent confusing contributors (you can currently find some around the Mandriva web sites, e.g. [2]).

Synch status shown in report tables is useless if triggered only when the translated file is committed, like it was for 2008.1: this way, if an author updates an English file and forgets to warn translators himself on the mailing list, nobody will notice the change and all translated files will be outdated!

Please make the system show useful diffs!

• diffs must not go crazy just because of different XML code layouts caused by two contributors using two different text editors;

suggestion: maybe this could be worked around by applying the following operations to the two files before doing the diff:

1. reduce all multiple whitespaces and tabs to single spaces;
2. remove newlines;
3. apply some automated code formatting (tidy?); this could actually make the previous two points redundant.

• structure diffs (regarding XML tree structure of the file) must not go crazy for insignificant changes or even unavoidable ones, especially when the "synch" status of the file is triggered by these diffs. e.g. for 2008.1 the file was reported out of synch even because of a difference in the xml:lang attribute, which is unavoidable, or because of missing or added <foreignphrase> and <quote> tags, which might happen when adapting a text to a different language.

suggestion: build a list of XML elements and attributes which will be ignored when doing the diff. On the other hand, if you think those elements can be meaningful sometimes, you could make the system show TWO diffs: a "strict" one (the old way), and a more "relaxed" one.

Put a creation date in ALL SVNNav report pages, it will help spot bugs earlier, e.g. when reports are not being generated for some reason, and it can help understanding if e.g. a report page on a particular file has been generated before or after a commit you made.