Hi Frank, Below are some inputs based on my experiences. Installed help system ================== [1] Discoverability: The search facility can be improved. It does not have an index. Users often know what task to do but not in which document section the related information is located. Having a good search and index makes it possible to discover the sections of the documentation. (JDS help comes nowhere near openoffice.org help facility).
[2] Accessibility: When a user reads documentation related to a particular task, it would be very useful if related information is accessible with relative ease. Ex: details such as "See Also", "Related tasks", "Related Tools", "Examples", "Related articles/tutorials", "Links to newsgroups/online forums" Tagging helps a lot in accessibility. (This we already see in online blogs and google provided tools/searches) Such accessibility currently does not exist in any of the Linux/Unix desktops including Gnome. [3] The help system needs to have a user feedback facility. After a uses does the search, there should be a question available in an unobtrusive manner that asks "Did you get the content you were looking for" - with facility for user to provide inputs. (Can this be tied to a online system where if the answer is no, it gets posted as a question to a forum online and on meaningful resolution, gets into the regular documentation). [4] Mechanism for easy user contribution: Make it easy for "any desktop user" to be able to contribute without the need to know docbook If there are open areas where documentation is required, the help installed on the system can have such questions marked as "contribution required" and a facility for users to edit and contribute through a easy submit mechanism. It can have pointers to style-guides and rules-of-submission as relevant. Users can also be provided with facility to submit articles via help system. This facility need not appear in release(production) systems but can appear in SXDE kind of releases that is targetted towards developers/contributors. This facility for ex, can get enabled only if a foohelp-doc-devel.pkg is installed on top of foohelp-doc.pkg --------------------------------------------------------------------------------------------------------------------------- NOTE: Due to gaps in [1] & [2] I often find myself reaching out to google, newsgroups archives, online forums/archives, IRCs instead of the manuals. This gap doesn't get easily captured since there is no easy means to provide feedback (gap in [3]). That brings to [4] - users cannot easily contribute to help system for the ones they found the fix since 'how & where to contribute' will need its own search, tooling, docs to go through, etc. About docs.sun.com ================== [1] Content wise there is tons of information here. Usability and Accessibility is not good. I remember that long back I wanted to search for instructions related to "Oracle RAC - Solaris Volume Manager - Solaris Cluster - Solaris 10". It took me considerable time to identify the relevant sections spread across different documents. Even this was possible since I did a find/grep in readmes in the software dvd that I had downloaded. The 4 phrases that I needed together didn't seem to be used in conjunction (subsequently a couple of docs have come out). Tagging and User inputs to the tagging can do wonders in such situations. ** docs.sun.com is wonderful as desktop references, providing better accessibility would make it wonderful for all sorts of trouble shooting situations. ** [2] Whenever I search for information related to sun technologies in google, I rarely find output from docs.sun.com. It is invariably from mail archives and in the recent past opensolaris forums and blogs. Bigadmin articles also appear in the google output. Why not docs.sun.com? This already has so much of relevant content !!! best regards Shiv On 8/1/07, Frank Peters <fpe at sun.com> wrote: > Hi there, > > my name is Frank Peters and I am working for Sun's > Information Products Group mainly on documentation > for OpenOffice.org. We're planning to having > a closer look at the documentation of the > Solaris GNOME desktop. > > Generally, we feel that the GNOME desktop comes with > a decent amount of documentation that makes it well > usable for the average user (at least I'm not having > any problems using it on Solaris or Linux). > > We would like to make a documentation assessment > of the OpenSolaris GNOME desktop to find the gaps > in the GNOME docs that would require our attention. > > These are critical pieces missing in the documentation > that make it harder to work productively of efficiently > with the desktop. > > Given the high amount of expertise in this group I would > like to ask you for your help on this. I would like to > learn from you what gaps you have encountered in the > documentation during your work with the GNOME > desktop on OpenSolaris or Solaris. > > During our assessment exercise we would also like > to share our findings with you and ask you for input. > > So: do you see any critical gaps in the documentation > for the OpenSolaris GNOME desktop? If so, what are they? > > Thanks for your help > Frank > > > _______________________________________________ > desktop-discuss mailing list > desktop-discuss at opensolaris.org >
