[opensuse-doc] The openSUSE distribution chages are way ahead of documentation?
Versions of suse are coming in so fast pace that documentation writers and translators have no chance to follow the changes, and that is for sure systematic error that is taken over from Linux (open source) development process. It is obvious from amount of changes that are introduced almost daily that nobody has in mind that documentation is part of software, just as much as source code and binaries. There is no successful open source project that failed to deliver documentation. We all like to mention some well documented projects like Samba, but when it comes to do the same, we have problem to deliver easy to read documents. The example that came in mind is very important article http://en.opensuse.org/Additional_YaST_Package_Repositories that must have different links for each version and is written as single page with some notes for 10.0 and 10.1 that resemble more on C defines that on human readable text. Missing general FAQ, as well as one for each version, that is easy to reference in support effort on mail lists and Usenet groups (forums). Actually missing general concept how to organize documentation is probably the worst of all problems. One idea to start from is to use as base SUSE version, just as it is given on download sources. Why? Because there is logical explanation and a technical reason to sort FTP server directories first by computer architecture, second by SUSE version, than to have installation sources, additional sources, updates, etc. What is the best method to publish that kind of document structure? What is the best way to bring documents and packages together? Would be the directory structure good, as it allows to bring in the same directory our own contributions with original author manual pages, help files etc. It will make easier to see where original software documentation is short and add more content instead of starting from scratch every time. Mediawiki software that is structured to support well Wikipedia type of data that has not many similar articles that differs only in few lines. Is the usage of structure: opensuse.org/10.0/ opensuse.org/10.1/ opensuse.org/10.2/ appropriate, or it is better to use name spaces? Please add your comments and ideas. Helping to organize documentation is just as important as to bring in the latest software version. -- Regards, Rajko. Visit http://en.opensuse.org/ --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
I believe that in order to solve documentation problem, community must help. In order for the community to help, we need tools - that is wiki (which exists on the webpage) *and* a conversion tool to convert that wiki to RPM to install offline. There is *no* such conversion tool available, and so it makes me much less interested to contribute to wikis, because they are not installed in the final distro. I agree to contribute more articles to our openSUSE wiki *only* if Novell agrees to distribute this as RPM on the standard openSUSE DVD ISO. Until today I have contributed few items: such as "FreeNX" server & "Qemu" configuration articles to wiki, but those are not included in the final distro, which makes me very unhappy about continuing contribution... To Novell: please allow the community to write docs, that will be included in the distro for offline use (in RPM package, HTML format).
On Saturday 30 September 2006 11:03, Alexey Eremenko wrote:
I believe that in order to solve documentation problem, community must help.
In order for the community to help, we need tools - that is wiki (which exists on the webpage) *and* a conversion tool to convert that wiki to RPM to install offline. There is *no* such conversion tool available, and so it makes me much less interested to contribute to wikis, because they are not installed in the final distro.
I agree to contribute more articles to our openSUSE wiki *only* if Novell agrees to distribute this as RPM on the standard openSUSE DVD ISO.
Until today I have contributed few items: such as "FreeNX" server & "Qemu" configuration articles to wiki, but those are not included in the final distro, which makes me very unhappy about continuing contribution...
To Novell: please allow the community to write docs, that will be included in the distro for offline use (in RPM package, HTML format).
I agree with the sentiments of your message. However, I am not a lover of wiki. Wiki is a content Motel. everything check-in, but nothing ever checks out. Porting wiki to more useful formats such as Docbook XML or DITA is a RPITA and adds an additional step in the process of packaging. However, I do agree that a web-based solution does reduce the barrier to entry for just anyone who wants to contribute something in the way of docs. One idea I have been playing with is th evision of editing Docbook under a web-based editor. So giving wiki-like docbook editing capabilities. This could help eliminate the problem of preprocessing wiki stuff to Docbook. If the source remains as docbook it would also make integration with the current toolchain used by the doc team much easier. It would also enable people that donot want to use a wiki-like enviroment, to edit the docbook src as a working copy of SVN. In short the level of indirection between editing environments would be greatly improved. There is a project that is a Joomla component, called docbook::collab. This demonstrates the direction I am thinking in. However, docbook::collab currently has some retrictions. 1. It uses BitFlex Editor. This supports creation of sdocbook. OK you can import full-docbook, but only edit using sdocbook. 2. It stores documents in MySQL. Not he best place to have these resources if you want SVN and piping into the build and translation processes. Perhaps people could look at this type of solution? -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Sean Wheller wrote:
On Saturday 30 September 2006 11:03, Alexey Eremenko wrote:
I believe that in order to solve documentation problem, community must help.
In order for the community to help, we need tools - that is wiki (which exists on the webpage) *and* a conversion tool to convert that wiki to RPM to install offline. There is *no* such conversion tool available, and so it makes me much less interested to contribute to wikis, because they are not installed in the final distro.
I agree to contribute more articles to our openSUSE wiki *only* if Novell agrees to distribute this as RPM on the standard openSUSE DVD ISO.
Until today I have contributed few items: such as "FreeNX" server & "Qemu" configuration articles to wiki, but those are not included in the final distro, which makes me very unhappy about continuing contribution...
To Novell: please allow the community to write docs, that will be included in the distro for offline use (in RPM package, HTML format).
I agree with the sentiments of your message.
However, I am not a lover of wiki. Wiki is a content Motel. everything check-in, but nothing ever checks out. Porting wiki to more useful formats such as Docbook XML or DITA is a RPITA and adds an additional step in the process of packaging.
The Docbook is marked as default format, but I've never seen any editor mentioned that will help document writers to concentrate on writing, not on learning of document source format, and all other stuff like conversion methods to different formats, that has little to do with actual writing.
However, I do agree that a web-based solution does reduce the barrier to entry for just anyone who wants to contribute something in the way of docs. One idea I have been playing with is th evision of editing Docbook under a web-based editor. So giving wiki-like docbook editing capabilities.
Editor? Like mentioned above.
This could help eliminate the problem of preprocessing wiki stuff to Docbook. If the source remains as docbook it would also make integration with the current toolchain used by the doc team much easier. It would also enable people that donot want to use a wiki-like enviroment, to edit the docbook src as a working copy of SVN. In short the level of indirection between editing environments would be greatly improved.
There is a project that is a Joomla component, called docbook::collab. This demonstrates the direction I am thinking in. However, docbook::collab currently has some retrictions. 1. It uses BitFlex Editor. This supports creation of sdocbook. OK you can import full-docbook, but only edit using sdocbook. 2. It stores documents in MySQL. Not he best place to have these resources if you want SVN and piping into the build and translation processes.
Perhaps people could look at this type of solution?
I hope they will. Though except small intro I wasn't able to find (guess what) documentation: http://forge.joomla.org/sf/docman/do/listDocuments/projects.docbook_collab/d... In the meantime we can think about what else we would need. - The templates and forms as a help for occasional contributors is what we are missing right now. - The tools (ways) to announce that we plan work on some documents, the searchable database of already active projects, and their status. This will give us ability to see active, stale and unmaintained projects. Projects that need help. The idea is pretty much the same as sourceforge.net, but with focus on SUSE related aspects. - The categorization, naming structure. I started that, jdd started that, and everything didn't moved from the beginning. If you ask me for the links, I lost even that. It is on the openSUSE wiki :-) (this sounds as helpful, as many help files) -- Regards, Rajko. Visit http://en.opensuse.org --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Just a short remark to this thread: Novell has a documentation team working on our manuals, nothing has changed here (see http://en.opensuse.org/Documentation_Team). It's not developers writing manuals, it's dedicated editors - some of them coming from development and others from other areas. Since we have a holiday on tuesday, most of us take a long weekend (monday of as well), so don't expect direct feedback on this by the documentation team. Somebody mentioned that software is only finished at the end - this is not completely true since openSUSE. My goal is to get features in early so that they can be tested and documented early. It's still very tight for the documentation team but it was even worse before;-(. Cheers, Andreas -- Andreas Jaeger, aj@suse.de, http://www.suse.de/~aj/ SUSE Linux Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
Andreas Jaeger wrote:
Just a short remark to this thread:
Novell has a documentation team working on our manuals, nothing has changed here (see http://en.opensuse.org/Documentation_Team). It's not developers writing manuals, it's dedicated editors - some of them coming from development and others from other areas.
Since we have a holiday on tuesday, most of us take a long weekend (monday of as well), so don't expect direct feedback on this by the documentation team.
Somebody mentioned that software is only finished at the end - this is not completely true since openSUSE. My goal is to get features in early so that they can be tested and documented early. It's still very tight for the documentation team but it was even worse before;-(.
Cheers, Andreas
Thanks for the response Andreas. I know that developers don't write documentation, at Novell, but in the most of small projects they do, and that is where serious improvement is needed. Novell/SUSE guys are trying hard to bring people in, but still, one needs too much to learn before can start contributing. One preconfigured package/pattern that contains all available software for documentation writing, for instance SVN with links to Novell repositories, editor with Novell like templates, and probably much more, will make volunteers life easier and move focus from tools to content. I hope that documentation guys will have some answers, instructions, ideas, as we need some in order to get involved. My idea of ideal world of documentation writer is one browser where one can read existing manuals, howto's etc, than when something was found start editor and change document. When done, submit for approval, proofreading and that's it. After some time get feedback, if it is accepted or not, or in need of further changes additions. In this world somebody else will think how to structure whole documentation, where to move balance, how to name articles. -- Regards, Rajko. Visit http://en.opensuse.org --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Rajko M a écrit :
- The categorization, naming structure. I started that, jdd started that, and everything didn't moved from the beginning. If you ask me for the links, I lost even that. It is on the openSUSE wiki :-) (this sounds as helpful, as many help files)
the true problem is _not_ the editor, but the structure. As you may know, generating docbook with a text processor is like generating a program from a program generator: a mess even a wiki can do a very good job as documentation generator, given the pages are related to a structure. but everybody have seen the time necessary to have a front page (we don't have it yet? sorry for that :-) and meaningfull menus :-). not to mention the same debate on the "documentation" page :-). practically, I'm stuck on the last but one chapter of Starcraft Broodwar and if I can't defeat the Protos, what seems likely, I will come back here :-) First of all, we must make the difference between the openSUSE native applications, generally called YaST (but also Zen...) and the more general applications. We must focus on yast, because nobody else will do it for us :-) So can anybody list exacltly the products of this kind remaining on the 10.2 openSUSE? (Yast, SaX2, Zen, SUSEFirewall2, SIGA, SUSEConfig... ?) to be constructive, I opened a sub chapter in the documentation page: http://en.opensuse.org/Documentation#openSUSE_internals_Documentation (this page should really have a TOC. I commented the NOTOC tag in the page source, uncomment it if you want) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hello, I am Ruediger Steffan, located in Germany, and would like to volunteer in writing and/or translating documentation. My job is customer advisor for telecommunication and DSL. In spare time I am distance-studying industrial engeneering and will start with degree dissertation in spring 2007. It would be nice to hear from you and get some hints where to start. Greets, Ruediger
Ruediger Steffan wrote:
Hello, I am Ruediger Steffan, located in Germany, and would like to volunteer in writing and/or translating documentation. My job is customer advisor for telecommunication and DSL. In spare time I am distance-studying industrial engeneering and will start with degree dissertation in spring 2007. It would be nice to hear from you and get some hints where to start.
Greets, Ruediger
As you can see Steffan, we are discussing where to start, so if you have will to help, watch this thread, and links that we refer to. That way you can make your own idea where are the problems, and what would be good to do. Editing help on wiki is always welcome. The main tool for now is openSUSE wiki at http://en.opensuse.org, and as native German speaker, you may find interesting http://de.opensuse.org . Jean (jdd) added some links to the: http://en.opensuse.org/Documentation#openSUSE internals Documentation so you can login to wiki and start writing articles. -- Regards, Rajko. Visit http://en.opensuse.org/MiniSUSE --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Rajko M wrote: ....
Jean (jdd) added some links to the: http://en.opensuse.org/Documentation#openSUSE internals Documentation so you can login to wiki and start writing articles.
Sorry for the link. It should be: http://en.opensuse.org/Documentation#openSUSE_internals_Documentation -- Regards, Rajko. Visit http://en.opensuse.org/MiniSUSE --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
jdd wrote:
Rajko M a écrit :
- The categorization, naming structure. I started that, jdd started that, and everything didn't moved from the beginning. If you ask me for the links, I lost even that. It is on the openSUSE wiki :-) (this sounds as helpful, as many help files)
the true problem is _not_ the editor, but the structure.
I agree. That is what I can't get right, the idea, how to organize all. For the God knows what time, I'm stuck trying to find out how to structure articles in one complex group of articles, this time it is about Troubleshooting ( http://en.opensuse.org/User:Rajko_m/Tests ), and I really need professional writer advice how to overcome this.
As you may know, generating docbook with a text processor is like generating a program from a program generator: a mess
As usually in the life, tool doesn't do the job, but human using it.
even a wiki can do a very good job as documentation generator, given the pages are related to a structure.
I agree. One important point is to see specifics of openSUSE related articles, and see what tools on the wiki are the most appropriate.
but everybody have seen the time necessary to have a front page (we don't have it yet? sorry for that :-) and meaningfull menus :-). not to mention the same debate on the "documentation" page :-).
The debate about front page is open, the only problem is that we have to decide about purpose of the front page, and set limits on number of items that we want to introduce.
practically, I'm stuck on the last but one chapter of Starcraft Broodwar and if I can't defeat the Protos, what seems likely, I will come back here :-)
:-D Serious problem.
First of all, we must make the difference between the openSUSE native applications, generally called YaST (but also Zen...) and the more general applications.
We must focus on yast, because nobody else will do it for us :-)
The YaST and a company, is resting primarily with Novell/SUSE doc team. For sure, we can help translating to languages that we know, but the process is still missing clear structure. Where to pick up source, what tools to use, where to deliver results for approval, who will give feedback to volunteer, what kind of feedback, etc. Actually, the same process, once defined, can be applied to any documentation, not only YaST related.
So can anybody list exactly the products of this kind remaining on the 10.2 openSUSE? (Yast, SaX2, Zen, SUSEFirewall2, SIGA, SUSEConfig... ?)
Let we try, and see what doc and devel guys can add/subtract.
to be constructive, I opened a sub chapter in the documentation page:
http://en.opensuse.org/Documentation#openSUSE_internals_Documentation
(this page should really have a TOC. I commented the NOTOC tag in the page source, uncomment it if you want)
jdd
-- Regards, Rajko. Visit http://en.opensuse.org/MiniSUSE --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Rajko M a écrit :
The YaST and a company, is resting primarily with Novell/SUSE doc team.
but is still poorly documented, as SuSE folks focused on the administrator guide on general Linux infos (making probably the better book ever on the subject)
process is still missing clear structure. Where to pick up source, (...)
this is not structure in the way I mean it. This is tools. Of course it's very usefull, certainly necessary, but the structure I speak of is the organisation of the documentation itself. what chapters, what titles, what page names (for the wiki), what categories... we all worked on that one day or an other, but the result is still very unperfect, I know of pages I can't find again (even page I did write myself :-() Part of the solution is probably to work on the wiki (as a base tool) like if it was a book. that is no search engine, no google, but as many Table of Content/index as we want. once this structure well formed (and the "portal" sub structure is a good example), it should be looked for portals administrators. The only way to have a page up to date is to have one author responsible of that. This don't mean this page (portal) admin have to write all himself, on the contrary he should have only to manage the pages (as in "manage a team") Think of docbook "chapters", "articles", "titles". any body can write articles in a semi informal manner, given somebody gives the shape. 25 years ago, my wife wrote a "memoire" (wite paper) about computer aided english teaching. At that time I had only scholar english and she had a master :-), but I'm not too bad as organisation. so I took it's work, asked her the good questions and organised the document. It's a very interesting experience to organise a document you nearly don't understand Our goal now is similar, but the document is much bigger, the author nearly impossible to have at hand (and I have 25 years more :-(), so the task is very difficult. but, in fact, we don't have to do this right now for an exam. It will go it's pace, slowly, and we can hope the result will be better and better when the time passes :-) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
jdd wrote:
Rajko M a écrit :
The YaST and a company, is resting primarily with Novell/SUSE doc team.
but is still poorly documented, as SuSE folks focused on the administrator guide on general Linux infos (making probably the better book ever on the subject)
Basic problem with Linux, including SUSE, is that, even if there is dedicated team, document writers never had enough time to do their job. Detailed program description without examples is few times bigger text than program itself, and it takes more time to write it. The description is just base document and it can be used to write all other readme, guides, etc. Writing all documents straight from a source code is just as bad idea as writing program before you define what you want to do with it and tools that you need to achieve goals.
process is still missing clear structure. Where to pick up source, (...)
Misunderstanding. I talk about writing and submission *process structure* not documentation structure. Besides wiki, I have n o clear idea how SUSE documentation process works. How one volunteer can help writing documentation if he/she has no idea where to start without interfering with SUSE process. What I see now is that they keep volunteers completely outside. We write our, they write their, and that's it. There is no joint effort, there is no coordination. It is not surprise that many people don't want to waste their time in disharmonious, inefficient effort. ....
Of course it's very usefull, certainly necessary, but the structure I speak of is the organisation of the documentation itself. what chapters, what titles, what page names (for the wiki), what categories...
we all worked on that one day or an other, but the result is still very unperfect, I know of pages I can't find again (even page I did write myself :-()
Part of the solution is probably to work on the wiki (as a base tool) like if it was a book. that is no search engine, no google, but as many Table of Content/index as we want.
once this structure well formed (and the "portal" sub structure is a good example), it should be looked for portals administrators.
The only way to have a page up to date is to have one author responsible of that. This don't mean this page (portal) admin have to write all himself, on the contrary he should have only to manage the pages (as in "manage a team")
Long time ago I wrote this: We need volunteers to lead projects, give shape, define tasks, be a focal point of project development. Loose groups waste a lot of energy for duplicated efforts. (http://en.opensuse.org/Tasks)
Think of docbook "chapters", "articles", "titles". any body can write articles in a semi informal manner, given somebody gives the shape.
25 years ago, my wife wrote a "memoire" (white paper) about computer aided english teaching. At that time I had only scholar english and she had a master :-), but I'm not too bad as organisation. so I took it's work, asked her the good questions and organised the document. It's a very interesting experience to organise a document you nearly don't understand
Our goal now is similar, but the document is much bigger, the author nearly impossible to have at hand (and I have 25 years more :-(), so the task is very difficult.
but, in fact, we don't have to do this right now for an exam. It will go it's pace, slowly, and we can hope the result will be better and better when the time passes :-)
jdd
Can I take that you are taking ownership of Administration Portal (or Index)? -- Regards, Rajko. Visit http://en.opensuse.org/MiniSUSE --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Rajko M a écrit :
Can I take that you are taking ownership of Administration Portal (or Index)?
admin is too large a goal :-) and I have already the task of admin of fr.opensuse.org, so I would like to let to others the portal administration of course I can and will participate. The french wiki lives now without my constant attention :-) and I will participate more in english one. but like I said, it's probably better to begin with yaST tools documentation jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
jdd wrote:
Rajko M a écrit :
Can I take that you are taking ownership of Administration Portal (or Index)?
admin is too large a goal :-) and I have already the task of admin of fr.opensuse.org, so I would like to let to others the portal administration
of course I can and will participate. The french wiki lives now without my constant attention :-) and I will participate more in english one.
but like I said, it's probably better to begin with yaST tools documentation
YaST tools have to be put somewhere, and that is Administration :-) This is what I'm going to do in a following days (weeks). Index all pages locally. It is only little bit more than 1000 articles including trash. Try to sort them as administration or usage content, weed out trash, and put that back on the wiki. Than we can continue discussion what's next. -- Regards, Rajko. Visit http://en.opensuse.org/MiniSUSE --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Alexey Eremenko a écrit :
To Novell: please allow the community to write docs, that will be included in the distro for offline use (in RPM package, HTML format).
as a very lon time linudoc contributor, I know quite well the problem, but have no simple solution :-( A goos documentation have to be well organised/structured and this is simply not the ordinary way of thinking of most people. Wikipedia IS a very good information source, but not so well organised (and can't be better, probably). SuSE manuals used to be very good, thanks to a very good writing team (and probably very expensive too). The goal should be to have a much bigger (with tranlations) documentation with nearly the same money. I do not have a solution. CVS or SVN are of course a good step forward. writing and translating doc is a very hard work, and even more as a voluntary work - I myself took some vacation from suse documentation for a month now, exausted by 6 month of continuous work. the truth is that documentation should be written 3 month ahead of the final product (for translating and printing delays) and this is quite impossible if we always wan to freeze the distro at the last minute jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
jdd wrote:
Alexey Eremenko a écrit :
To Novell: please allow the community to write docs, that will be included in the distro for offline use (in RPM package, HTML format).
That would be one solution too. Included rpm for HowTo is probably example of the way you would like to have wiki articles. Take Mediawiki software output, strip it to the bare minimum, and put in packages.
as a very long time linudoc contributor, I know quite well the problem, but have no simple solution :-(
A good documentation have to be well organised/structured and this is simply not the ordinary way of thinking of most people.
Right. The problem is that current core team are all (or majority) software developers (programmers). They know what software will do (most of the time), and for them is hard to imagine how far is few notes that one get with --help option from usable instructions how to use software.
Wikipedia IS a very good information source, but not so well organised (and can't be better, probably).
I'm afraid that everybody is expecting too much from wiki self organizing and healing. It is fine for Wikipedia where you don't have demand for articles (descriptions, instructions) to be in sync with anything. With openSUSE wiki that doesn't work as article about program can't follow 2 years after program is written. It has to be published in the same time as software, and updated every time developer changes program.
SuSE manuals used to be very good, thanks to a very good writing team (and probably very expensive too).
For me, that was one of the reasons to stay with SUSE so long. I can remember the style was excellent for the beginner and advanced user as well.
The goal should be to have a much bigger (with tranlations) documentation with nearly the same money. I do not have a solution. CVS or SVN are of course a good step forward.
The SVN is good step if you have tools and documentation how to use them. Step by step explanation how to check out, how to submit changes, what tools to use to edit. Documentation about this tools used in specific SUSE environment. Yes, documentation about how to contribute documentation trough SVN and other means would be super.
writing and translating doc is a very hard work, and even more as a voluntary work - I myself took some vacation from suse documentation for a month now, exausted by 6 month of continuous work.
I can see that :-D
the truth is that documentation should be written 3 month ahead of the final product (for translating and printing delays) and this is quite impossible if we always wan to freeze the distro at the last minute
jdd
That will keep happening as long as programmers will think that the job is done when they are done. The plain truth that takes in account only physical activity (not thinking how to write something) is that program source code is condensed explanation what program will do, so to write documentation one needs more time than program writer. How much more? I would say few times more just to explain program structure, input and output data structure of functions, what are limitations of used algorithms (like where it is optimal to use), examples of usage. For occasional contributors, document writers, we would need templates or even forms easy to fill in. This way there will be mentioned all that is necessary to know about program. -- Regards, Rajko. Visit http://en.opensuse.org --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Saturday 30 September 2006 10:53, Rajko M wrote:
Please add your comments and ideas. Helping to organize documentation is just as important as to bring in the latest software version.
Rajko its worse than that. SuSE documentation sources are not in a revision control repo despite the fact that such a repo was setup. As such there is a barrier to entry for open collaboration and contribution on documentation sources. Once SuSE documentataion process embraces the open source workflow and provides the infrustructure to support it, then the collective eye and brain of the community can assist the doc team who at this point are just developing in a hole. To fix the problems you mention in a manner that is sustainable, we need to address the above first. Then community and doc-team can move forward together and discuss how this is going to work and what we can do to address problems, make life easier. Translators need input also and implimentation of the pot/po file format generated from Docbook XML and places in a batch environment using diff etc can help to reduce the workload. Hope this helps, -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hello, Am Samstag, 30. September 2006 10:53 schrieb Rajko M: [...]
Mediawiki software that is structured to support well Wikipedia type of data that has not many similar articles that differs only in few lines. Is the usage of structure: opensuse.org/10.0/ opensuse.org/10.1/ opensuse.org/10.2/ appropriate,
This structure makes it hard to place pages that are valid for multiple releases - you'll at least need lots of redirects ("/10.2/sometopic -> /10.1/sometopic") I'd vote for opensuse.org/sometopic/10.0 (and opensuse.org/sometopic for version-independend texts). If the changes are small, you can also do "inline versioning" by writing "in SUSE Linux 10.1, ...." or using the Template:VersionNote. Well, I'm afraid there is no perfect solution for multi-version documentation, but there are better and worser ones ;-)
or it is better to use name spaces?
No, I don't think so - namespaces ("10.1:sometopic") have the same problem I already explained for /10.1/sometopic. If you want, you can additionally use categories ("Category:10.1") because this way allows articles to be valid for multiple versions - but keep in mind that you'll have to add another category ("Category:10.2") to all artices that are still valid in 10.2. (Yes, many things change, but even more things do not change - so this will cause lots of work ;-) Regards, Christian Boltz -- Kurz gefasst: /etc/crontab ist IMHO so nützlich wie eine Laus in einem Raumanzug - es juckt, aber Du kannst Dich nicht kratzen, es sei denn, Du bist Gott auf Deinem System. Und dann weisst Du noch nicht mal, ob Du anstelle der Laus Deine Nase amputiert hast. [Jan Trippler in suse-linux] --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Christian Boltz wrote:
Hello,
Am Samstag, 30. September 2006 10:53 schrieb Rajko M: [...]
Mediawiki software that is structured to support well Wikipedia type of data that has not many similar articles that differs only in few lines. Is the usage of structure: opensuse.org/10.0/ opensuse.org/10.1/ opensuse.org/10.2/ appropriate,
This structure makes it hard to place pages that are valid for multiple releases - you'll at least need lots of redirects ("/10.2/sometopic -> /10.1/sometopic")
I'd vote for opensuse.org/sometopic/10.0 (and opensuse.org/sometopic for version-independend texts).
If the changes are small, you can also do "inline versioning" by writing "in SUSE Linux 10.1, ...." or using the Template:VersionNote.
Well, I'm afraid there is no perfect solution for multi-version documentation, but there are better and worser ones ;-)
or it is better to use name spaces?
No, I don't think so - namespaces ("10.1:sometopic") have the same problem I already explained for /10.1/sometopic.
If you want, you can additionally use categories ("Category:10.1") because this way allows articles to be valid for multiple versions - but keep in mind that you'll have to add another category ("Category:10.2") to all artices that are still valid in 10.2. (Yes, many things change, but even more things do not change - so this will cause lots of work ;-)
Regards,
Christian Boltz
Thanks for the comment Christian. That was a day ago when I was asking this :-) I was looking for some idea, and I wasn't really convinced that either mentioned in that post was good. There is no perfect solution if one looks to achieve multiple goals. I would set primary goals to: - easy to find for anyone, (including me :-) ) and - easy for article writers. If that are prim directives, than more work is granted, whatever structure will be. Someone has to go after article is written and do some proofreading, formating, indexing etc. That is how that works in any branch of publishing, we can't expect that the same rules doesn't apply to us. Indexes (or Portals) are the easiest way to organize content. I prefer word Index as it is the same data structure, with the same purpose like the book index. Portals have the same purpose with added content, so once we have Index we can design portal. Why not to add articles to categories? I can search and link in index few pages for the time that I need to add category to one article. I tried to add categories before, and I did indexing too. It is lesser work with additional benefit that Index(es) can have more different layouts without touching underlaying software. Categories are good for Wikipedia type and amount of data, but as you mentioned it is too much work to do the same for software distribution. -- Regards, Rajko. Visit http://en.opensuse.org --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hi, this thread took many twists and turns, so I'd like to summarise what has been discussed so far and comment on it. I would also like to explain the differences between the documentation that is shipped with the openSUSE distribution and the Wiki. Last but not least I will announce a future documentation project (Lessons for Lizards, LSL), that will hopefully address some of the critics issued in this thread. For those who know me from the opensuse-wiki list (hello Rajko, jdd and Christian ;-) ): I am not only part of the wiki team - my primary function is being a writer on the SUSE documentation team. Shipped manuals vs. openSUSE wiki --------------------------------- Current state is, that we have two kinds of documentation for the openSUSE distribution: * shipped manuals * openSUSE wiki The approach of the shipped documentation is to guide the user through the installation (Start-Up guide), to give a general overview of the user interface (KDE and GNOME guides), to enable him to configure and run enhanced services (Reference guide, AppArmor). It is designed to help the majority of users, regardless of knowledge, hardware, etc. The documentation is updated with each openSUSE release (approx. every 6-8 months). The shipped manuals are written by the Novell/SUSE documentation team at different sites across the world. They are derived from the "official" product documentation of various Novell/SUSE products. Because product documentation has to follow a product specific structure, company internal styleguides, QA and other internal processes, it can't be open in the usual sense. Consequently the derivative shipped with openSUSE also can't be fully open, too. So there are only limited possibilities for the community to participate: via bugzilla, Novell doc comment system or via this list. Furthermore we welcome everyone who is willing to contribute for a certain topic on a case by case basis. Please also see the LSL announcement at the end of this mail. The XML sources are shipped with the opensuse distribution (therefore it is possible to send us patches), the DTD is available from NovellForge (see http://en.opensuse.org/Documentation_Team for details). The (majority) openSUSE documentation has a different approach. A lot of articles are designed to help with problems with specific hardware or configurations. Part of the documentation on openSUSE also present solutions for bugs or explain how to enhance the distribution and how to use unsupported stuff like, for instance, Xgl. Other articles illustrate the configuration of services not covered in the shipped manuals (e.g. setting up a mailserver). In the ideal case the openSUSE Wiki documentation is updated whenever there is need to. It is our (that is the documentation team) belief, that the documentation on the openSUSE Wiki is the ideal and indispensable complement. The fact that the openSUSE Wiki documentation is - at least theoretically ;-) - always "bleeding edge" is the main reason for the fact, that it is not shipped with the distribution. Some articles would probably already be outdated the day the iso images are published. For this very reason we stopped shipping the SDB (Support database) with S.u.S.E. Linux a few years ago. It is also our belief that it is absolutely necessary to have two different sources for documentation - a "static" one that is shipped with the distribution and a flexible one that is available online. In fact this is the case since at least S.u.S.E. Linux 4.2 (1996) when the SDB was born on www.suse.de. Thread summary -------------- (lines with my comments are starting with "# ") 1. Content ^^^^^^^^^^ 1.1 Documentation is not up-to-date due to the rapid development process and the fact that documenting software is not too popular with developers. 1.2 Version specific FAQs are missing 1.3 The software itself (man pages, help files etc.) is poorly documented. 2. Structure/Organisation ^^^^^^^^^^^^^^^^^^^^^^^^^ 2.1 A general concept on how to organise documentation on the openSUSE Wiki is missing. Solution 1 (Rajko): The structure should depend on the openSUSE versions - either use a directory based structure or name spaces # Lot's of documentation is not necessarily # version specific, so such a structure will # make it difficult to maintain such documents # This issue has been brought up frequently and I agree that it is # one of, if not _the_, most important issues that is to be solved # for opensuse.org. I would suggest to move this discussion to # opensuse-wiki, because there are more people participating in that # list and because it was brought up on that list in the past. It # was my plan to revitalise this discussion once the 10.2 # documentation is out the door (mid October) and the new starting # pages are in place (Oct 20th, hopefully). # In this context we should IMHO also discuss the search function, # because a wiki is not the best solution when you want to have # structured documentation. A real good search engine helps. # If you want me to start and moderate the discussion (as I did with # the starting page discussion), please give me another two weeks... 3. Participation ^^^^^^^^^^^^^^^^ 3.1 Motivation to contribute is low because the openSUSE Wiki documentation content is not shipped with the distribution. # See above - the main advantage of a Wiki article is the fact, that # it is always up-to-date (at least theoretically). It would make # little sense to ship documentation that is outdated. Please also # see the LSL announcementat the end of the mail - hopefully this is # a compromise you can live with. 3.2 SUSE keeps volunteers completely outside. We write our, they write their, and that's it. There is no joint effort, there is no coordination. It is not surprise that many people don't want to waste their time in disharmonious, inefficient effort. # Please see above and the LSL announcement below. 3.3 The SuSE documentation process needs to be public # Please see above and the LSL announcement below. 4. Tools ^^^^^^^^^ 4.1 A Wiki is a "content Motel" that makes it almost impossible to convert it contents to other formats (such as XML, for instance). A tool that produces a convertible source and is ridiculously easy to use is needed. Solution 1 (Sean): docbook::collab http://forge.joomla.org/sf/docman/do/listDocuments/projects.docbook_collab/d... # It is my strong belief, that a writer has to know the # document source format he is using inside out - otherwise he will # never ever produce data that is re-usable and convertible. This # does not only apply to TeX, XML and the like, but also to M$ Word, # OpenOffice and other tools. 4.2 We need a single tool that allows one to browse, read, edit, submit, proofread documentation and that has a workflow implemented. # You are looking for a Document Management System other than a # Wiki. Usually very expensive and not open source ;-) Project announcement: Lessons for Lizards ------------------------------------------ Triggered by Sean's mail in August (http://lists.opensuse.org/opensuse-doc/2006-08/) we (the documentation team) seriously started to think about how we could open up our processes an accept contributions from the community. As already said, existing processes make it impossible for us to open up our complete documentation. So we came up with the idea of a project we called "Lessons for Lizards". We initially planned to announce this project in December, because some basics (especially the xml to Wiki stylesheets) will not be ready until then. This thread made us rethink that decision. Nevertheless, the tools will not be ready before December... . Please tell us what you think about the project - nothing is carved in stone, yet. This is just a collection of ideas we came up with, so far. What is Lessons for Lizards (LSL)? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The idea behind Lessons for Lizards is to have a SUSE cookbook (cookbook is trademarked by O'Reilly, so we cannot use that name). It should contain recipes for certain tasks not covered in the printed manual, such as for instance "How to install and configure SUSE without YaST", "Setting up a mailserver", "Compiling a new Kernel", etc. (these topics are, of course, hypothetical - I hope you get the idea). It is our belief, that such a book is currently missing and would be very useful for many users. Who can contribute? ^^^^^^^^^^^^^^^^^^^^ Everybody who is willing to ;-). The documentation team is also willing to participate. Under which license will LSL be published? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Not decided, yet - proposals are welcome (should be an open source license, of course). Will LSL be shipped with the distribution? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Yes, it will be treated as the other manuals shipped with openSUSE. In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook). In which output formats will LSL be available? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HTML, PDF, Wiki (more on Wiki below) What tools will Novell/SUSE provide? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * the complete build environment SUSE uses to build it's books (including stylesheets, scripts, etc.) as an RPM package * a SVN server on which the LSL sources are hosted (read/write access for everybody) * a style guide * support (on this mailing-list) I have already written articles that would fit into the book on the wiki. What about them? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The SUSE documentation team is willing to manually convert each Wiki article that would fit into the book into docbook xml. Authors may contact us through this list. How can I make sure my article is updated in both the wiki and the book? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ toms, our xsl guru, has written stylesheets that convert docbook xml into Wiki language, so the xml source would be the single source to produce Wiki and "LSL output". At the moment. these stylesheets are work in progress and the Wiki output needs to be beautified manually. We hope to have a better version available in December. If you would like to help us with these stylesheets, please contact my by mail. -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.novell.com/ "Reality is always controlled by the people who are most insane" Dogbert --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hello SUSErs ! About DocBook: One thing that afraids me is that I know *no* software that can edit DocBook. If OpenOffice can make DocBooks, or there is other user-friendly software to do that then ok. About Offline Wiki: I think, that we could have actually on *offline wiki*, that is, instead of converting formats back & forth, just use the current Wiki's as-is, but build it on top of offline HTML files, that will be linked to SUSE Start Menu. Even if Wiki requires some serverside technology, (which I am not sure), such as PHP, this is still not a problem. We could make "embedded" version of Apache + PHP, that work on some special TCP port and works only with loopback interface, so this is solvable & secure. That way we can have a full web, wiki experience on Home Desktops, that are not connected to the Internet. (such as poor people, or disconnected for security reasons) -Fenix*NBK*, 5.10.2006.
Hallo Alexey, On Thursday 05 October 2006 20:18, Alexey Eremenko wrote:
About DocBook: One thing that afraids me is that I know *no* software that can edit DocBook.
There are lots of XML editors! You can find a list here[1] that support DocBook, both free and commercial. Most users probably use Emacs/PSGML for XML authoring although it is not restricted to that editor. Purists prefer vi. ;)
If OpenOffice can make DocBooks, or there is other user-friendly software to do that then ok.
Define "user-friendly". ;) WYSYWYG (What you see is what you get) editors are nice to write some letters to your grandma. From my experience they distract you from your text, because you are more busy layouting your text than writing it. :) (Ok, I stretched my argument a bit.) It takes maybe some time to get used to it. However, what you gain in efficiency, speed and portability is invaluable. Of course, DocBook would be too much just for writing a letter (although it is possible.) OpenOffice.org (OOo) *can* export to DocBook---however that doesn't mean that it creates meaningful DocBook XML. OOo can not enforce the structure like a real XML editor. Exporting to XML and writing in XML are two different things.
[...]
Bye, Tom ------ [1] http://wiki.docbook.org/topic/DocBookAuthoringTools -- ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ http://www.suse.com 90409 Nuernberg, Germany _\_v --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Thursday 05 October 2006 11:02, Frank Sundermeyer wrote:
Hi,
Hello Frank :-)
this thread took many twists and turns,
Just as any discussion about problem that has no simple solution, and actually has not only one soution, but many of them, and parties can't meet and discuss topic before it goes public. So ideas are mentioned, and discarded as they show as unpractical. ...
Shipped manuals vs. openSUSE wiki ---------------------------------
Current state is, that we have two kinds of documentation for the openSUSE distribution:
* shipped manuals * openSUSE wiki
My concern, and reason to start the thread is not to criticize anybody as I was able to imagine how it works, and your explanation just confirmed that. I was looking at documentation problem in Linux that is transfered to SUSE. A lot of obsolete, inaccurate, sparse documentation, lack of examples how to use applications. There is huge pile of documentation to read, check accuracy and completness, contact original authors, see where they want to go. ....
Thread summary 1. Content 1.1 Documentation is not up-to-date due to the rapid development process and the fact that documenting software is not too popular with developers. 1.2 Version specific FAQs are missing
1.3 The software itself (man pages, help files etc.) is poorly documented.
This is about any Linux documents. Some projects keep up, the other not. The speed of changes, including SUSE distribution, is so fast that no one can tell that certain package will be in the next release. That demotivates people to even try to review documents, and even lesser to add content.
2. Structure/Organisation ^^^^^^^^^^^^^^^^^^^^^^^^^
2.1 A general concept on how to organise documentation on the openSUSE Wiki is missing. Solution 1 (Rajko): The structure should depend on the openSUSE versions - either use a directory based structure or name spaces
# Lot's of documentation is not necessarily # version specific, so such a structure will # make it difficult to maintain such documents
If we would use indexes, instead of Categories, or subpages, than keeping articles grouped by architecture, than by version is viable, and much better alternative than present status, where even frequent visitors to wiki are surprised that some article is written, some other is just a stub, and sometimes under nice title is just "This page is under construction".
# This issue has been brought up frequently and I agree that it is # one of, if not _the_, most important issues that is to be solved # for opensuse.org. I would suggest to move this discussion to # opensuse-wiki, because there are more people participating in that # list and because it was brought up on that list in the past. It # was my plan to revitalise this discussion once the 10.2 # documentation is out the door (mid October) and the new starting # pages are in place (Oct 20th, hopefully). # In this context we should IMHO also discuss the search function, # because a wiki is not the best solution when you want to have # structured documentation. A real good search engine helps. # If you want me to start and moderate the discussion (as I did with # the starting page discussion), please give me another two weeks...
We can discuss Wiki organization and part of documents that will be placed there, on opensuse-wiki, but methods to synchronize code development and documentation writing, are still better to discuss here. It should be permanent effort, to change developers ideas about documentation importance. That effort should not be limited to distribution, as SUSE is already documented better than then the rest. It has to go out and bug software developers to provide more details.
3. Participation 3.1 Motivation to contribute is low because the openSUSE Wiki documentation content is not shipped with the distribution.
# See above - the main advantage of a Wiki article is the fact, that # it is always up-to-date (at least theoretically). It would make # little sense to ship documentation that is outdated. Please also # see the LSL announcementat the end of the mail - hopefully this is # a compromise you can live with.
I agree that wiki is good to offer fast solution for burning problem, but to limit it deliberately only to that function, is not good in the world where online resources are first that user try to find once the system is up and running. It is also necessary to have classic books, for the time and cases where online is not available, for the functions that doesn't change much with the time. The Lesson for Lizards is fancy name, but it will not change need for documentation organization structure, as well as page structure and formating. The kind that is not necessary to learn much to understand and contribute. That is another reason for thoughts about WYSWYG editor tools. How that would work? Download template for article that you write, fill all fields, and you have good looking article, with all sections included. Upload it to wiki. Done.
3.2 SUSE keeps volunteers completely outside. We write our, they write their, and that's it. There is no joint effort, there is no coordination. It is not surprise that many people don't want to waste their time in disharmonious, inefficient effort.
This was really complaint about Wiki articles and the way it works. Basic is that some coordination must exist. I bet that there will be more volunteers if each would be able to pick some task from list, not to wonder all over the place in order to find something to do.
# Please see above and the LSL announcement below.
3.3 The SuSE documentation process needs to be public
^ :-) Novell - SUSE - openSUSE. I just noticed. You are talking about Novel and SUSE, and only wiki is openSUSE. I just save few strokes "open" if I say SUSE.
# Please see above and the LSL announcement below.
4. Tools ^^^^^^^^^
4.1 A Wiki is a "content Motel" that makes it almost impossible to convert it contents to other formats (such as XML, for instance). A tool that produces a convertible source and is ridiculously easy to use is needed. Solution 1 (Sean): docbook::collab
http://forge.joomla.org/sf/docman/do/listDocuments/projects.docbook_collab/ docman.root
# It is my strong belief, that a writer has to know the # document source format he is using inside out - otherwise he will # never ever produce data that is re-usable and convertible. This # does not only apply to TeX, XML and the like, but also to M$ Word, # OpenOffice and other tools.
The writer has to know the tools and what is possible to do with them, but need to know source format tells that tools are missing.
4.2 We need a single tool that allows one to browse, read, edit, submit, proofread documentation and that has a workflow implemented.
# You are looking for a Document Management System other than a # Wiki. Usually very expensive and not open source ;-)
I thought something that can mimic such system. For software that works like: Download existing source, change it, submit patches for review. Done. Similar for new sources. The only thing that doesn't exist is task execution control that is needed in environments where people get paid for the work done.
Project announcement: Lessons for Lizards ------------------------------------------
Triggered by Sean's mail in August (http://lists.opensuse.org/opensuse-doc/2006-08/) we (the documentation team) seriously started to think about how we could open up our processes an accept contributions from the community.
As already said, existing processes make it impossible for us to open up our complete documentation. So we came up with the idea of a project we called "Lessons for Lizards".
We initially planned to announce this project in December, because some basics (especially the xml to Wiki stylesheets) will not be ready until then. This thread made us rethink that decision. Nevertheless, the tools will not be ready before December... .
Please tell us what you think about the project - nothing is carved in stone, yet. This is just a collection of ideas we came up with, so far.
What is Lessons for Lizards (LSL)? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The idea behind Lessons for Lizards is to have a SUSE cookbook (cookbook is trademarked by O'Reilly, so we cannot use that name). It should contain recipes for certain tasks not covered in the printed manual, such as for instance "How to install and configure SUSE without YaST", "Setting up a mailserver", "Compiling a new Kernel", etc. (these topics are, of course, hypothetical - I hope you get the idea). It is our belief, that such a book is currently missing and would be very useful for many users.
Who can contribute? ^^^^^^^^^^^^^^^^^^^^ Everybody who is willing to ;-). The documentation team is also willing to participate.
Under which license will LSL be published? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Not decided, yet - proposals are welcome (should be an open source license, of course).
Will LSL be shipped with the distribution? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Yes, it will be treated as the other manuals shipped with openSUSE.
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
In which output formats will LSL be available? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HTML, PDF, Wiki (more on Wiki below)
What tools will Novell/SUSE provide? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * the complete build environment SUSE uses to build it's books (including stylesheets, scripts, etc.) as an RPM package * a SVN server on which the LSL sources are hosted (read/write access for everybody) * a style guide * support (on this mailing-list)
Good. ... -- Regards, Rajko M. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Thursday 05 October 2006 18:02, Frank Sundermeyer wrote:
What is Lessons for Lizards (LSL)? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The idea behind Lessons for Lizards is to have a SUSE cookbook (cookbook is trademarked by O'Reilly, so we cannot use that name). It should contain recipes for certain tasks not covered in the printed manual, such as for instance "How to install and configure SUSE without YaST", "Setting up a mailserver", "Compiling a new Kernel", etc. (these topics are, of course, hypothetical - I hope you get the idea). It is our belief, that such a book is currently missing and would be very useful for many users.
I think the idea of LSL is good, but does not address the core of the problems: * Proper recognition and addressing of community request to participate in "all" documentation development related to openSuSE. * Willingness to address and resolve the problems that hinder release of all openSuSE documentation source Much of this thread has focused on technology, tools and the challenge of how to write, when it should be discussing the decision to make available documentation sources, that still seem to be withheld, to which members of open community wish to contribute. It is my understanding that the intent behind openSuSE is to be an open and free distribution that is a community owned project. It therefore stands to reason that this should apply to documentation. The idea of LSL just takes community focus off of the real problem, the inability to release all the documentation sources related to openSuSE. If openSuSE wants a community relationship in the area of documentation, then then some people should realize that unless this problem is addressed, it will always come back to haunt. The only way to address the problem is for all documentation, and the source, that would be packaged in openSuSE to be made available under open license and placed in a collaborative infrustructure. What I am going to say next is just my feeling, though I do detect similar feelings from one or two of the people discussing here. It is not neceserily the desire of every person to spend days and hours writing books, LSL is a case in point. Most community members want to be in a position that when they spot a problem with existing documents, they can fix it. The important thing here is that "they can fix it" themselves. This is a key component to building any documentation community. People are not there to sit on the sides, make a few comments and hope that changes get made. They want to be a "part of" the development, and they want to have "some control" that will come with a "level of ownership". It is this level of contribution that is most valuable as it serves to provide some level of maintenance and sustainability. To ignore this desire, as is presently being suggested, would be arrogant on the part of those who currently decide what happens with openSuSE. In light of this, if openSuSE documentation efforts are to have community support, then the whole source and nothing but the whole source needs to be available under free and open license. Furthermore, where, when and how members of the community decide to contribute is a decision for the community in conjunction with the the Documentation Team, not the Documentation Team alone.
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
What tools will Novell/SUSE provide? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * the complete build environment SUSE uses to build it's books (including stylesheets, scripts, etc.) as an RPM package
And as source in the SVN mentioned below.
* a SVN server on which the LSL sources are hosted (read/write access for everybody)
It's not about LSL. Nice idea, but I am looking for the current documentation sources to be available before commiting to writing new documents. Access needs to be controlled until such time as people have made enough contribution and have demonstrated responsability. In the interim, everyone can checkout a working copy and svn update as and when changes happen. Patches can at first be applied by core persons. I suggest starting with the doc team and then adding responsible persons.
How can I make sure my article is updated in both the wiki and the book? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ toms, our xsl guru, has written stylesheets that convert docbook xml into Wiki language, so the xml source would be the single source to produce Wiki and "LSL output". At the moment. these stylesheets are work in progress and the Wiki output needs to be beautified manually. We hope to have a better version available in December. If you would like to help us with these stylesheets, please contact my by mail.
We developed the same thing over at Ubuntu-doc, in fact it was round tripped. This has challenges, but is possible. It would be better to put the xsl source in svn where people can look at it and decide if they can contribute. Once again, holding source in a hole is not the way forward for an open source community. Sorry if this message is contentious, but I think we need to be able to face facts head-on and in plain view. Hope this helps, -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Monday 09 October 2006 09:08, Sean Wheller wrote:
On Thursday 05 October 2006 18:02, Frank Sundermeyer wrote:
Hi,
I think the idea of LSL is good, but does not address the core of the problems:
* Proper recognition and addressing of community request to participate in "all" documentation development related to openSuSE.
* Willingness to address and resolve the problems that hinder release of all openSuSE documentation source
sorry for not having been clear enough. I will try again ;-): At the moment, we have two branches of documentation for openSUSE, both of _equal importance_: the openSUSE Wiki and the shipped documentation. We are _not_ able to completely open the shipped documentation for openSUSE because of the following reasons: * the manuals shipped with openSUSE are spinoffs of Novell product documentation. Product documentation has to follow company internal styleguides, QA and other internal processes like scheduled translation. Creating this documentation is tightly connected to the products with regard to structure, content and timing. It is written in close cooperation with product management by the people in the Novell documentation departments all over the world. These manuals contain parts that are suitable for openSUSE, too. These parts are used to create the manuals shipped with openSUSE. This way the shipped manuals are not exclusively openSUSE but are an excerpt from the product documentation. * we have one common repository for all Linux documentation at Novell (single source approach). As mentioned above, openSUSE is just a part of it, this repository includes documentation for SUSE Linux Enterprise Server, SUSE Linux Enterprise Desktop and SUSE Linux Point of Sale as well. * the documentation sources for the different projects are _not_ separated - most files contain parts only used for a specific product (we are profiling a lot - single source approach) Because of these reasons, it is not possible to create an open svn and accept contributions from outside. It is also not possible to completely separate the openSUSE documentation from all other Novell Linux documentation, because this would create a workload we will not be able to handle (it would be a merging nightmare). However, this does _not_ mean the community can not contribute. Apart from contributing via bugzilla and the Novell doc comment system, anybody can send us patches - the profiled xml sources are shipped with the openSUSE distribution. ---------- We did _not_ invent the LSL project in order to conceal the fact that we will not completely open our documentation - as you can see, we are pretty open about that ;). We initially came up with the cookbook idea because we are very fond of the cookbook series from O'Reilly and are using some of these books for our daily work. We thought the openSUSE users would benefit from such a book, too. We were also very much aware, that a lot of stuff that is currently on the openSUSE Wiki would very well fit into such a book. So, additionally inspired by your initial question to open the SUSE documentation, the idea for a community project was born.
Much of this thread has focused on technology, tools and the challenge of how to write, when it should be discussing the decision to make available documentation sources, that still seem to be withheld, to which members of open community wish to contribute.
This is not true - see the suselinux-manual source packages. They contain the (profiled, see above) xml sources for the shipped documentation.
It is my understanding that the intent behind openSuSE is to be an open and free distribution that is a community owned project. It therefore stands to reason that this should apply to documentation.
The idea of LSL just takes community focus off of the real problem, the inability to release all the documentation sources related to openSuSE.
As stated more than once - the documentation sources _are_ available. With the upcoming susedoc rpm package for LSL everybody will even be able to create books from these sources with just one single command. Correct me if I'm wrong, but I have the strong impression that for you everything besides "providing an svn where everybody can check in/out openSUSE documentation" means "closed documentation development". I do not share that opinion.
If openSuSE wants a community relationship in the area of documentation, then then some people should realize that unless this problem is addressed, it will always come back to haunt. The only way to address the problem is for all documentation, and the source, that would be packaged in openSuSE to be made available under open license and placed in a collaborative infrustructure.
Our documentation _is_ under the GFDL license, so everyone can do with it whatever this license allows. Not having an "open" SVN does not mean the documentation is not available under an open source license ;-).
What I am going to say next is just my feeling, though I do detect similar feelings from one or two of the people discussing here.
It is not neceserily the desire of every person to spend days and hours writing books, LSL is a case in point. Most community members want to be in a position that when they spot a problem with existing documents, they can fix it.
There are also quite a lot of community members that contribute very valuable documentation to the Wiki. LSL will give them a second platform where they will receive more recognition and which will also make it very clear how valuable their contributions are.
The important thing here is that "they can fix it" themselves. This is a key component to building any documentation community. People are not there to sit on the sides, make a few comments and hope that changes get made. They want to be a "part of" the development, and they want to have "some control" that will come with a "level of ownership". It is this level of contribution that is most valuable as it serves to provide some level of maintenance and sustainability.
In the essence, I agree with you. But to me you make it sound like "If I cannot get 100% I don't want to have anything".
To ignore this desire, as is presently being suggested, would be arrogant on the part of those who currently decide what happens with openSuSE.
There are facts to be honoured and these facts do not allow us to completely separate 50% (the other 50% being the wiki) of the openSUSE documentation from the rest of Novell's product documentation. You also have to be aware that it's a learning curve for us and LSL is a start we will surely learn from ;-).
In light of this, if openSuSE documentation efforts are to have community support, then the whole source and nothing but the whole source needs to be available under free and open license.
It already is - see the suselinux-manual source packages and the package's license information.
Furthermore, where, when and how members of the community decide to contribute is a decision for the community in conjunction with the the Documentation Team, not the Documentation Team alone.
We made one proposal - LSL. If the community has better ideas and convinces everybody, so be it. We just will not open the core manuals as is for now, so we will not reach agreement there - therefore let's talk about things that can be done ;-)
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
Novdoc is 100% docbook compatible and just excludes some docbook tags.
What tools will Novell/SUSE provide? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * the complete build environment SUSE uses to build it's books (including stylesheets, scripts, etc.) as an RPM package
And as source in the SVN mentioned below.
We are not using any proprietary tools (except XEP for building PDFs (because there is no alternative), but that can be replaced by FOP- with some restrictions), but scripts instead. So there is no need for an extra source package. This package will also be available within the openSUSE build service (and therefore be under revision control, if I am not wrong).
* a SVN server on which the LSL sources are hosted (read/write access for everybody)
It's not about LSL. Nice idea, but I am looking for the current documentation sources to be available before commiting to writing new documents.
see above.
It would be better to put the xsl source in svn where people can look at it and decide if they can contribute. Once again, holding source in a hole is not the way forward for an open source community.
We have no intention of holding source in a hole. The susedoc rpm will be available on the build service and will be shipped with openSUSE (at the moment I do not know whether it will be ready for 10.2, but we will create the project on the build service ASAP). -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ Reality is always controlled by the people who are most insane Dogbert --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Monday 09 October 2006 21:25, Frank Sundermeyer wrote:
On Monday 09 October 2006 09:08, Sean Wheller wrote:
On Thursday 05 October 2006 18:02, Frank Sundermeyer wrote:
At the moment, we have two branches of documentation for openSUSE, both of _equal importance_: the openSUSE Wiki and the shipped documentation.
I am focused on shipped documentation.
We are _not_ able to completely open the shipped documentation for openSUSE because of the following reasons:
* the manuals shipped with openSUSE are spinoffs of Novell product documentation. Product documentation has to follow company internal styleguides, QA and other internal processes like scheduled translation. Creating this documentation is tightly connected to the products with regard to structure, content and timing. It is written in close cooperation with product management by the people in the Novell documentation departments all over the world. These manuals contain parts that are suitable for openSUSE, too. These parts are used to create the manuals shipped with openSUSE. This way the shipped manuals are not exclusively openSUSE but are an excerpt from the product documentation. * we have one common repository for all Linux documentation at Novell (single source approach). As mentioned above, openSUSE is just a part of it, this repository includes documentation for SUSE Linux Enterprise Server, SUSE Linux Enterprise Desktop and SUSE Linux Point of Sale as well. * the documentation sources for the different projects are _not_ separated - most files contain parts only used for a specific product (we are profiling a lot - single source approach)
Because of these reasons, it is not possible to create an open svn and accept contributions from outside. It is also not possible to completely separate the openSUSE documentation from all other Novell Linux documentation, because this would create a workload we will not be able to handle (it would be a merging nightmare).
The jam is understood. The breaker is that you don't want to parse the Docbook XML using the openSuSE profile to produce a new set of Docbook XML containing only openSUSE and then place that into community SVN. Reasoning, you would have to merge changes from community SVN back into Novell SVN.
However, this does _not_ mean the community can not contribute. Apart from contributing via bugzilla and the Novell doc comment system, anybody can send us patches - the profiled xml sources are shipped with the openSUSE distribution.
I see that. This makes me think that if internally you are not able to give community only openSuSE documentation, then community willing could transform the XML to new XML (openSUSE only) and proceed regardless of the internal doc effort. Community could also produce its own doc RPM. Just thinking aloud as though the shoe would be on the other foot :-) I assume that shut a fork would not meet with internal approval and would therefore not be recognized as official.
----------
We did _not_ invent the LSL project in order to conceal the fact that we will not completely open our documentation - as you can see, we are pretty open about that ;).
That's a relief :-)
Much of this thread has focused on technology, tools and the challenge of how to write, when it should be discussing the decision to make available documentation sources, that still seem to be withheld, to which members of open community wish to contribute.
This is not true - see the suselinux-manual source packages. They contain the (profiled, see above) xml sources for the shipped documentation.
What I am saying is that the source (SVN) of the source (XML) is not available to persons outside of Novell. As a result during development, it is not easily possible to get hold of updates done to the documentation source until such time as it becomes available in RPM and this, while understandable, is contrary to an open development model.
It is my understanding that the intent behind openSuSE is to be an open and free distribution that is a community owned project. It therefore stands to reason that this should apply to documentation.
The idea of LSL just takes community focus off of the real problem, the inability to release all the documentation sources related to openSuSE.
As stated more than once - the documentation sources _are_ available. With the
upcoming ^^^^^^^^^^^^ until then is there a way to contribute?
susedoc rpm package for LSL everybody will even be able to create books from these sources with just one single command. Correct me if I'm wrong, but I have the strong impression that for you everything besides "providing an svn where everybody can check in/out openSUSE documentation" means "closed documentation development". I do not share that opinion.
Correct. The process of being able to collaborate on documents during development phases is hindered by the fact that community cannot access the Novell SVN. Sure the source is in the RPM, but that is a delay in the process and means that contributive changes can only be made once a RPM is available.
If openSuSE wants a community relationship in the area of documentation, then then some people should realize that unless this problem is addressed, it will always come back to haunt. The only way to address the problem is for all documentation, and the source, that would be packaged in openSuSE to be made available under open license and placed in a collaborative infrustructure.
Our documentation _is_ under the GFDL license, so everyone can do with it whatever this license allows. Not having an "open" SVN does not mean the documentation is not available under an open source license ;-).
I agree your license is open. What I am saying is that the development process is not. I am sure you will agree that it is much easier to develop when everyone can see the changes before packaging.
The important thing here is that "they can fix it" themselves. This is a key component to building any documentation community. People are not there to sit on the sides, make a few comments and hope that changes get made. They want to be a "part of" the development, and they want to have "some control" that will come with a "level of ownership". It is this level of contribution that is most valuable as it serves to provide some level of maintenance and sustainability.
In the essence, I agree with you. But to me you make it sound like "If I cannot get 100% I don't want to have anything".
It would be better to have at least a working copy, without commit access, of the source during development. At least then changes can be viewed and contributions made in a more productive manner. Tasks could be identified, published and shared amongst anyone in the community wishing to take on a task. Patches can be checked and approved/disapproved by internal members.
To ignore this desire, as is presently being suggested, would be arrogant on the part of those who currently decide what happens with openSuSE.
There are facts to be honoured and these facts do not allow us to completely separate 50% (the other 50% being the wiki) of the openSUSE documentation from the rest of Novell's product documentation. You also have to be aware that it's a learning curve for us and LSL is a start we will surely learn from ;-).
Understood, but from openSuSE community perspective, does anyone really care about Novell documents? Personally, I don't, so I am not really concerned with how community contributions end up in Novell products. The interest is with openSuSE not NLD or other stuff.
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
Novdoc is 100% docbook compatible and just excludes some docbook tags.
When you customize the DTD it is no longer Docbook :-) It is Novdoc.
It would be better to put the xsl source in svn where people can look at it and decide if they can contribute. Once again, holding source in a hole is not the way forward for an open source community.
We have no intention of holding source in a hole. The susedoc rpm will be available on the build service and will be shipped with openSUSE (at the moment I do not know whether it will be ready for 10.2, but we will create the project on the build service ASAP).
I think I am looking to get involved before the build services. Before the fact rather than after. Perhaps I stand alone in this sentiment. If so then let me rather shut my mouth and keep the peace. I'll go along with what you already are already prepared to do. If I am not alone, then it would be good to hear others voices. -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Monday 09 October 2006 15:19, Sean Wheller wrote:
It would be better to have at least a working copy, without commit access, of the source during development. At least then changes can be viewed and contributions made in a more productive manner. Tasks could be identified, published and shared amongst anyone in the community wishing to take on a task. Patches can be checked and approved/disapproved by internal members.
That is what I mentioned using example with old fashioned way to contribute patches for programs. No one with sense for reality will ask for direct write access, because of certain rules that Frank mentioned, but read access with monitored write access, is something that will only help documentation team. But, I would not wait for Godot. My Indexing project is more than halfway done. In a week or two, I'll ask for opinion on content. I hope that will solve some problems that we have now. -- Regards, Rajko M. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hello, (extremely shortening the quote to the IMHO most important part, intentionally skipping lots of discussion about openness etc.) Am Montag, 9. Oktober 2006 21:25 schrieb Frank Sundermeyer:
Because of these reasons, it is not possible to create an open svn and accept contributions from outside. It is also not possible to completely separate the openSUSE documentation from all other Novell Linux documentation, because this would create a workload we will not be able to handle (it would be a merging nightmare).
May I propose a better solution than "wontfix"? Call it "DocuWichtl-Factory" ;-) or use any other name you like, but please honor the following proposals: - generate XML with the openSUSE part of the Novell Linux documentation daily (or even hourly - depending on how often you change something) - create a public SVN containing these daily/hourly snapshots - offer _read-only_ SVN access only to avoid the merging nightmare (read-only is not very nice, but it's the best we can have under the given conditions) - patches can be sent by mail, bugzilla, whatever instead. Maybe even a small tool for sending contributions ("svn diff | mail ...") can be provided. Advantages: - ways more up to date than a monthly (?) rpm package - external contributors can work on an up-to-date version instead of fixing a already fixed text - patches against the current version do more likely match against the Novell-internal XML files than patches against outdated versions - avoids the merging nightmare - changes are easy to identify ("svn diff" and/or a opensuse-doc-commit mailinglist) - avoids "forking" the documentation [1] - "the best we can (currently) have" What do you think about my proposal? Regards, Christian Boltz [1] although I don't think this will ever happen - even with "closed" documentation development -- Tut mir leid. Tu hast dich dafür entschieden, Computer zu benutzen. Aus irgendeinem Grunde glaubst du, das sei risikofrei. Ich versichere dir, daß es das nicht ist. Computer sind böse, rostige, alte Kettensägen, die grundlos anspringen. [Ratti in suse-linux] --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Monday 09 October 2006 18:32, Christian Boltz wrote:
Tut mir leid. Tu hast dich dafür entschieden, Computer zu benutzen. Aus irgendeinem Grunde glaubst du, das sei risikofrei. Ich versichere dir, daß es das nicht ist. Computer sind böse, rostige, alte Kettensägen, die grundlos anspringen.
Es ist leider war. -- Regards, Rajko M. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Monday 09 October 2006 18:41, Rajko M wrote:
Es ist leider war.
:-) Ich meinte Wahr. -- Regards, Rajko M. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Tuesday 10 October 2006 01:32, Christian Boltz wrote:
What do you think about my proposal?
Much more reasonable than, what I've heard thus far. -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Christian Boltz a écrit :
What do you think about my proposal?
very good... jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Monday 09 October 2006 18:32, Christian Boltz wrote:
What do you think about my proposal?
It is realistic. -- Regards, Rajko M. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Tuesday 10 October 2006 01:32, Christian Boltz wrote: Hi,
May I propose a better solution than "wontfix"?
Call it "DocuWichtl-Factory" ;-) or use any other name you like, but please honor the following proposals: - generate XML with the openSUSE part of the Novell Linux documentation daily (or even hourly - depending on how often you change something) - create a public SVN containing these daily/hourly snapshots - offer _read-only_ SVN access only to avoid the merging nightmare (read-only is not very nice, but it's the best we can have under the given conditions) - patches can be sent by mail, bugzilla, whatever instead. Maybe even a small tool for sending contributions ("svn diff | mail ...") can be provided.
Advantages: - ways more up to date than a monthly (?) rpm package - external contributors can work on an up-to-date version instead of fixing a already fixed text - patches against the current version do more likely match against the Novell-internal XML files than patches against outdated versions - avoids the merging nightmare - changes are easy to identify ("svn diff" and/or a opensuse-doc-commit mailinglist) - avoids "forking" the documentation [1] - "the best we can (currently) have"
What do you think about my proposal?
interesting proposal - we will think about it. At the moment we are busy with 10.2, so please give us some time before we make a decision. -- Regards Frank Frank Sundermeyer, SUSE LINUX GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.novell.com/ "Reality is always controlled by the people who are most insane" Dogbert --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hi, On Monday 09 October 2006 09:08, Sean Wheller wrote:
[...]
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
You misinterpreted that, he didn't claim that Novdoc is a standard. :) It's an exchange format intentionally with the same elements and structure like DocBook. Not more not less.
[...]
Tom -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Tuesday 10 October 2006 08:29, Thomas Schraitle wrote:
On Monday 09 October 2006 09:08, Sean Wheller wrote:
[...]
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
You misinterpreted that, he didn't claim that Novdoc is a standard. :) It's an exchange format intentionally with the same elements and structure like DocBook. Not more not less.
Oh I see. So what is the advantage of using Novdoc in the community? I mean isn't it just better to use the full docbook dtd and xsl's, perhaps with a customization layer from the onset? -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hi, On Tuesday 10 October 2006 08:53, Sean Wheller wrote:
On Tuesday 10 October 2006 08:29, Thomas Schraitle wrote:
On Monday 09 October 2006 09:08, Sean Wheller wrote:
[...]
In which format will LSL be written? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In DocBook xml (or novdoc, which is a subset of DocBook).
No, novdoc is not a standard. Docbook is a standard. So is DITA.
You misinterpreted that, he didn't claim that Novdoc is a standard. :) It's an exchange format intentionally with the same elements and structure like DocBook. Not more not less.
Oh I see.
So what is the advantage of using Novdoc in the community?
Well, just to make it clearer: The elements and structure are the same but as Frank wrote it is a bit more restricted than DocBook. Think of a kind of Simple DocBook DTD. At the moment it is an exchange format between Novell and SUSE only. For the communitiy it's a matter of taste: Some prefer more restricted DTDs others need the freedom to express their thoughts in a more verbose markup.
I mean isn't it just better to use the full docbook dtd and xsl's, perhaps with a customization layer from the onset?
Of course. :) For the LfL project I would recommend DocBook anyway as it is not as restricted than Novdoc. Tom -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Tel: +49-(0)911-740 53 131 Maxfeldstrasse 5 /\\ Documentation Specialist 90409 Nuernberg, Germany _\_v http://www.suse.com --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
On Tuesday 10 October 2006 09:15, Thomas Schraitle wrote:
On Tuesday 10 October 2006 08:53, Sean Wheller wrote:
I mean isn't it just better to use the full docbook dtd and xsl's, perhaps with a customization layer from the onset?
Of course. :) For the LfL project I would recommend DocBook anyway as it is not as restricted than Novdoc.
Yip, I don't think anyone much cares about how easy or not it is to exchange parts of documentation from community to Novell products. Now, if the Novell products where open and free, then that would be a different matter, but then there also would be no problem releasing all documentation into community :-) Just me being militant. -- Ask me about the Monkey. Sean Wheller Technical Author sean@inwords.co.za +27-84-854-9408 http://www.inwords.co.za --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hi, On Tuesday 10 October 2006 09:42, Sean Wheller wrote:
On Tuesday 10 October 2006 09:15, Thomas Schraitle wrote:
Now, if the Novell products where open and free, then that would be a different matter, but then there also would be no problem releasing all documentation into community :-)
See Franks mail. :-)
Just me being militant.
Just me being realistic. :) Tom P.S.: There is no need to CC me. I am subscribed to this list. :) -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Actually I understand Novell's decision not to open all of their docs. Also I think that Novell's Enterprise products can only win from LFL as well. I am a bit afraid of the new format, DocBook. Why use it ? I feel more comfortable with HTML for documentation.
Hi Alexey, On Tuesday 10 October 2006 10:22, Alexey Eremenko wrote:
[...] I am a bit afraid of the new format, DocBook. Why use it ? I feel more comfortable with HTML for documentation.
If you know how to write HTML then you shouldn't have any difficulties using DocBook. If you write in a single source environment HTML is not a good option. DocBook is one of the formats that is used frequently by documentation people (although DITA seems to get some speed, but that's another story.) DocBook is a stable DTD with very good XSLT stylesheets that can create HTML, Manpages, PDF and other useful things. Do you know the Linux Documentation Project[1]? A lot of documentation there is written in DocBook. KDE and GNOME use it too. And Subversion, and ... you got it. :) Tom ------- [1] http://www.tldp.org/ -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Thomas Schraitle a écrit :
I mean isn't it just better to use the full docbook dtd and xsl's, perhaps with a customization layer from the onset?
personnaly I think that the less tags the better and the first thing to do should be to show what tag gives what in SuSE manuals. This can be easily done giving an example with all (or most) of the tags and a pdf/jpg file with the printed result. Then this example could be used as a template. for LfL as I see it, 3/4 title levels, lists with and without numbers and tables should be enough. If I understand well most article wont be more than one page large (cookbook size). it could even be done with a web form. I think there is a online sgml/docbook tool on the Linux Documentation Project site http://tldp.org/ the tldp system can also be seen as an example (just a bit too static in my opinion) - see also here http://tldp.org/LDP/LDP-Author-Guide/html/process.html jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Thomas Schraitle a écrit :
You misinterpreted that, he didn't claim that Novdoc is a standard. :) It's an exchange format intentionally with the same elements and structure like DocBook. Not more not less.
and saying that a document is docbook compatible don't mind all the docbook tags have to be used in it :-) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
participants (9)
-
Alexey Eremenko -
Andreas Jaeger -
Christian Boltz -
Frank Sundermeyer -
jdd -
Rajko M -
Ruediger Steffan -
Sean Wheller -
Thomas Schraitle