[OpenIndiana-discuss] Documentation-Project
Hello OpenIndiana-Community, I am in an Open-Source-seminar at University, in which we have to hold a presentation about an Open-Source project and participate in the development-process of this project. I chose OpenIndiana for this Course, because I think it is an interesting young project and the developement of a free Solaris is important for the open-source-community. Becaus it lacks in a good documentation of OpenIndiana yet, as far as i read in the wiki, I had the idea of writing a script to transform the latest OpenSolaris documentation from XML to a Sphinx-documentation(restructuredText) and rewrite it in some parts. I think Sphinx is a wonderful tool to write a good documentation and export it to html and pdf. It might be easier to handle these documents than the XML ones. If you like the idea of writing the OpenSolaris-documentation in Sphinx, it might be helpful to integrate it in the revision control system to have an easy way to manage the documentation. On another point, it would help me for the presentation, if someone writes me, how decisions for the project are made and how the project is managed(commitments to the sourcetree and something like that) Sincerely yours, Tobias Famulla ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss
[OpenIndiana-discuss] Fwd: Re: [oi-dev] Documentation Systems
Hello, I forward the mail about the documentation system, because the feedback on the oi-dev list wasn't that much. Maybe it would help to start a maillinglist for the documentation after decide the basic points. Sincerely, Tobias Original-Nachricht Betreff:Re: [oi-dev] Documentation Systems Datum: Thu, 29 Sep 2011 21:00:57 +0200 Von:Tobias Famulla Antwort an: OpenIndiana Developer mailing list An: Volker A. Brandt , OpenIndiana Developer mailing list Hello Volker, I added the licences of the formats and the software to the document, after my holidays. The old documentation of OpenSolaris is licenced under Public Documentation Licence. http://hub.opensolaris.org/bin/view/Community+Group+documentation/tmp Sadly all documents I found about Solaris 11 Express are copyrighted by Oracle. http://download.oracle.com/docs/cd/E19963-01/ Because of this, the change of the format might not be that big issue, because we only have to do it once. Although other projects use DocBook with big success. I sadly never used DocBook or DITA by myself, yet. Sincerely, Tobias Am 06.08.2011 12:50, schrieb Volker A. Brandt: Hello Tobias! I summarized information about reStructuredText, DocBook and DITA. This is very interesting information, thank you. One thing that should also be investigated for each format is licensing, both things like definitions, DTDs, etc., and the licenses of the tools. In our company, we are using docbook + dblatex + pdflatex with very good results. The dblatex is actively and very well maintained by its original author. Regards -- Volker -- Jabber: b...@jabber.ccc.de ICQ:279837014 Handy: 0178-5545505 Skype: grund-rauschen ___ oi-dev mailing list oi-...@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss
Re: [OpenIndiana-discuss] Help with website
+1 I think a good documentation is most important. Normally I only use forums or mailing lists, if there is no answer in the doc or maybe in the wiki. I did a little research on documentation formats and posted the corrected files a week ago. I attached the files, so you don't have to search them. The thing I realized during the research was, that managing a documentation is not a trivial job. I think we should start a new doc mailing list and try to find a solution with the people who wants to help in this subject and the cooperating with the devs and the web-team. The Documentation of Freebsd in case of a classical documentation (Handbook pdf and html) and the german ubuntuusers-wiki (http://wiki.ubuntuusers.de/Startseite) are good examples for good and helpful documentations. I think it is a better solution to make a decision in the group than trying a huge amount of different systems by single persons. Sincerely, Tobias Famulla Am 09.10.2011 16:20, schrieb Alexander Lesle: > Hello List, > > my opinion is that when we want to get openindiana popular that we > need first a good documentation. Not only a good documentation for > geeks but rather also for endusers. > > Look at Ubuntu for the last 3 years. In the meantime they had a good > documentation and a active community where you get help when you have > problems. And they offered it in several languages because not > everyone understand English so good that he understand the man-pages. > > The openindiana wiki is outdated and confused, so I play in the last > two weeks with www.dokuwiki.org. It can be set multilingual but my > knowledge about openindiana is "half-depth" because I play with it > until one year. > > When we find enough engaged guys who want to help to bring up a > multilanguage documentation I will have a look for some webspaces. > > ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss
Re: [OpenIndiana-discuss] Help with website
Sorry, I forgot to attach the files. Am 10.10.2011 00:19, schrieb Tobias Famulla: > +1 > > I think a good documentation is most important. Normally I only use > forums or mailing lists, if there is no answer in the doc or maybe in > the wiki. > > I did a little research on documentation formats and posted the > corrected files a week ago. > I attached the files, so you don't have to search them. > > The thing I realized during the research was, that managing a > documentation is not a trivial job. > > I think we should start a new doc mailing list and try to find a > solution with the people who wants to help in this subject and the > cooperating with the devs and the web-team. > > The Documentation of Freebsd in case of a classical documentation > (Handbook pdf and html) and the german ubuntuusers-wiki > (http://wiki.ubuntuusers.de/Startseite) are good examples for good and > helpful documentations. > > I think it is a better solution to make a decision in the group than > trying a huge amount of different systems by single persons. > > Sincerely, > > Tobias Famulla > > Am 09.10.2011 16:20, schrieb Alexander Lesle: >> Hello List, >> >> my opinion is that when we want to get openindiana popular that we >> need first a good documentation. Not only a good documentation for >> geeks but rather also for endusers. >> >> Look at Ubuntu for the last 3 years. In the meantime they had a good >> documentation and a active community where you get help when you have >> problems. And they offered it in several languages because not >> everyone understand English so good that he understand the man-pages. >> >> The openindiana wiki is outdated and confused, so I play in the last >> two weeks with www.dokuwiki.org. It can be set multilingual but my >> knowledge about openindiana is "half-depth" because I play with it >> until one year. >> >> When we find enough engaged guys who want to help to bring up a >> multilanguage documentation I will have a look for some webspaces. >> >> > ___ > OpenIndiana-discuss mailing list > OpenIndiana-discuss@openindiana.org > http://openindiana.org/mailman/listinfo/openindiana-discuss > ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss
Re: [OpenIndiana-discuss] Help with website
Hello, Am 09.10.2011 17:58, schrieb Alexander Lesle: > Hello Josef 'Jeff' Sipek and List, > > On Oktober, 09 2011, 16:39 wrote in [1]: > >> On Sun, Oct 09, 2011 at 04:20:50PM +0200, Alexander Lesle wrote: >>> my opinion is that when we want to get openindiana popular that we >>> need first a good documentation. Not only a good documentation for >>> geeks but rather also for endusers. >> I see no reason why the two projects can't happen at the same time. Writing >> good documentation takes time (especially if it is multilingual). It would >> be silly to postpone everything else just to have documentation first. > When you understand my statement wrong then is it because my english > is not very well. IMHO we need docu, forum und mail-list and all can > benefit from each other. > >>> Look at Ubuntu for the last 3 years. In the meantime they had a good >>> documentation and a active community where you get help when you have >>> problems. And they offered it in several languages because not >>> everyone understand English so good that he understand the man-pages. >> When Ubuntu started off, they "inherited" a lot of good stuff from Debian. >> Perhaps we could use Sun's OpenSolaris documentation as a starting point? >> (Depends on the licensing, of course.) > I think that Oracle is not very amused and they deleted a lot of > informations in the web in the last months. > Lets us see what changes on opensolaris are done at maintenance this > weekend. the documentation was under Public Documentation Licence, but the page of opensolaris is temporary not available. How i read the Licence it is no problem to use the existing documentation and extend it. Of course we have to remove all trademarks of Oracle first. > >>> The openindiana wiki is outdated and confused, so I play in the last >>> two weeks with www.dokuwiki.org. It can be set multilingual but my >>> knowledge about openindiana is "half-depth" because I play with it >>> until one year. >> The wiki software itself is fine. It's the content that is lacking. > That's right. Feel free to contribute. > >>> When we find enough engaged guys who want to help to bring up a >>> multilanguage documentation I will have a look for some webspaces. >> I think, and I'm no expert, that the first step should be to have >> decent documentation in *one* language and then go on a translation rampage. >> Regardless, we need documentation. > Jep. > ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss
Re: [OpenIndiana-discuss] Help with website
Sorry, but i don't really see the point. Of course OS is different to Linux or BSD, but there are also differences between them. If you change from Windows or even Mac OS to a posix-like system the difference might be the largest, but there are a lot of people who use Linux on their notebooks or PCs. If I want to run a server on OpenIndiana, because I want to use ZFS and Zones, because they fit my needs, I only want a source, where I find the information, how to partition the system, how to build a pool, how to install a postgresql-server or something like that. I think if you have a good documentation and/or wiki and a possibility to communicate to the experts in a not to complicated way, the users will use OI if it fits their needs. Because OI might also not have the same use-cases than ubuntu, a newsgroup-server or a maillinglist might be fine. Tobias Am 10.10.2011 23:32, schrieb Dan Swartzendruber: A couple of thoughts: OSX is a dreadful wrong example. If you polled 1 million Mac users and asked them 'what OS runs under the hood?', my guess is 95% would have no idea what you are talking about. Secondly, throwing vague statements out about the 'shortcomings of linux' is at best non-helpful, and at worst discredits you. I am a Software Engineer, and it irks me to no end to have to retain N different tool/command sets in my memory for no good reason. Whether you like it or not, Linux (and to a lesser extent, the various BSD dialects) are what most folks know and are comfortable with. Presenting them with yet another flavor of Unix, with a command/tool set that is too distant is going to result in the person walking away and settling for redhat/ubuntu/debian or whatever. I kind of hinted at this in an earlier post - if I didn't have to use OI or some flavor of OS to get ZFS for my SAN, I would have gone elsewhere like a shot. BSD and Linux are pretty close when most of the commands are considered - OS is much less so, and that is what is going to relegate it to a niche system unless something changes. And no, I'm not an opposing fanboy or basher, just a realist... ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss -- Jabber: b...@jabber.ccc.de ICQ:279837014 Handy: 0178-5545505 Skype: grund-rauschen ___ OpenIndiana-discuss mailing list OpenIndiana-discuss@openindiana.org http://openindiana.org/mailman/listinfo/openindiana-discuss
