Hi,
I am new to this list. the reason I'm posting here is the following:
At the 'fedora-list' there has been a recent community effort to formulate a document with the "guidelines" for posting to that list. After a number of drafts and discussions, this document has reached a more mature form, and has been put in the form of a web page:
Original: http://www-personal.ksu.edu/~seabra/linux/FedoraRules.html Mirror: http://www.cwelug.org/fedora/FedoraRules.html
It is already considered "official", in the sense that it grew from discussions in the list that have reached a consunsus. As a next step, we would like to make this document know for most users of the list. For this, the suggestions we have are:
1. Monthly reminder: having a link or a text-only version of this document sent automatically monthly to all subscribers;
2. Part of a welcoming message: Either include a link in the welcoming message, or send a separate e-mail with the text-only version of the document to every new subscriber;
3. Linked to sign-up page: maybe there could be a link in the sign in page?
4. Link in the sugnature. (in **MY** opinion, this would likely be the most effective of all.) It would help if there could be a link in the signature added by RedHat to all messages distributed. The signature could then look something like: --** fedora-list mailing list fedora-list@redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-list Before posting to this list, please check << link here >>
4. Submission to Fedora-docs: That last suggestion was made to make this documet more "official".
So, that's where we are now. Please consider this message as a "submission" Unless there's another way to do it). We would really appreciate if the people responsibe could take a look at the page and consider accepting it, if it seems appropriate.
Thank you very much,
On Thu, 2005-03-31 at 12:26 -0600, Gustavo Seabra wrote:
Hi,
I am new to this list. the reason I'm posting here is the following:
At the 'fedora-list' there has been a recent community effort to formulate a document with the "guidelines" for posting to that list. After a number of drafts and discussions, this document has reached a more mature form, and has been put in the form of a web page:
Original: http://www-personal.ksu.edu/~seabra/linux/FedoraRules.html Mirror: http://www.cwelug.org/fedora/FedoraRules.html
This is great. It is succinct and useful. Thanks for bringing it here.
It is already considered "official", in the sense that it grew from discussions in the list that have reached a consunsus. As a next step, we would like to make this document know for most users of the list. For this, the suggestions we have are:
One immediate option that might make sense is to use the Wiki at fedoraproject.org. This works if the document is still in flux somewhat. Then it has an official-looking URL, and the others can mirror that.
However, if it's solid and not likely to get as many edits, then it seems to me like a perfect document for fedora.redhat.com/docs.
More on this below ...
- Monthly reminder: having a link or a text-only version of this document sent automatically monthly to all subscribers;
We can ask the Fedora list admin to include a link to the URL within the monthly mailing list reminder that Mailman sends out automatically.
- Part of a welcoming message: Either include a link in the welcoming message, or send a separate e-mail with the text-only version of the document to every new subscriber;
There is a welcome message to new list subscribers, and a custom message can be edited. I'd suspect the list maintainers would like to have a helpful URL.
- Linked to sign-up page: maybe there could be a link in the sign in page?
Same as above, it's a simple matter in the Mailman text.
Let's get the document at a permanent URL, and then finalize the request.
- Link in the sugnature. (in **MY** opinion, this would likely be the most effective of all.) It would help if there could be a link in the signature added by RedHat to all messages distributed. The signature could then look something like: --** fedora-list mailing list fedora-list@redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-list Before posting to this list, please check << link here >>
Same as above, simple matter via the Mailman interface.
- Submission to Fedora-docs: That last suggestion was made to make this documet more "official".
Yes, this is a good way to complete the circle.
So, that's where we are now. Please consider this message as a "submission" Unless there's another way to do it). We would really appreciate if the people responsibe could take a look at the page and consider accepting it, if it seems appropriate.
Now the hard part. :)
We can accept the submission, and the document will be easy to put into DocBook for maintenance. This has the advantage of providing the maintainer with a reference implementation in DocBook, in the maintainers don't know DocBook yet.
Someone needs to step-up to maintain this doc, keep it alive, handle bug reports against it, and update it as new ideas and changes come along. If the time comes to pass it along, the maintainer needs to be responsible and not drop the document.
Are you interested in this? Or someone else involved in the writing of the document? Take a look at this to see the process we use:
http://fedora.redhat.com/participate/documentation-quick-start/
We can get a writer to help with the conversion to DocBook and to get the author/maintainer started. Of course, the list is here to help with ongoing learning of DocBook, writing, etc.
- Karsten
Hi Gustavo, I see we've both ended up on this list after working on that guide. :-)
One immediate option that might make sense is to use the Wiki at fedoraproject.org. This works if the document is still in flux somewhat. Then it has an official-looking URL, and the others can mirror that.
However, if it's solid and not likely to get as many edits, then it seems to me like a perfect document for fedora.redhat.com/docs.
How about we do both? Make a permanant link for this version and stop calling it a draft - call it version 1. And another wiki version ready for any later changes?
http://fedora.redhat.com/participate/documentation-quick-start/
We can get a writer to help with the conversion to DocBook and to get the author/maintainer started. Of course, the list is here to help with ongoing learning of DocBook, writing, etc.
I would love to put it into DocBook, I've used XMLmind for DcoBook before and would love to start using am Opensource app. I'll read the quick-start guide over the weekend.
Duncan
On Thu, 31 Mar 2005 23:00:44 +0200, Duncan Lithgow duncan@lithgow-schmidt.dk wrote:
Hi Gustavo, I see we've both ended up on this list after working on that guide. :-)
One immediate option that might make sense is to use the Wiki at fedoraproject.org. This works if the document is still in flux somewhat. Then it has an official-looking URL, and the others can mirror that.
However, if it's solid and not likely to get as many edits, then it seems to me like a perfect document for fedora.redhat.com/docs.
How about we do both? Make a permanant link for this version and stop calling it a draft - call it version 1. And another wiki version ready for any later changes?
This seems a good idea. Although the document is mature enough, it would keep an open door for improvement.
http://fedora.redhat.com/participate/documentation-quick-start/
We can get a writer to help with the conversion to DocBook and to get the author/maintainer started. Of course, the list is here to help with ongoing learning of DocBook, writing, etc.
I would love to put it into DocBook, I've used XMLmind for DcoBook before and would love to start using am Opensource app. I'll read the quick-start guide over the weekend.
Great. I'll take a look at the Wiki think. And I don't mind the responsability to mantain it after it's ready. It is not likely to be a very demanding job anyway. I just cannot compromise for learning the DocBook stuff /now/: I'm already running late with my thesis and cannot spare much time for anything else for a couple of weeks at least...
Cheers,
On Mar 31, 2005 3:00 PM, Duncan Lithgow duncan@lithgow-schmidt.dk wrote:
Hi Gustavo, I see we've both ended up on this list after working on that guide. :-)
One immediate option that might make sense is to use the Wiki at fedoraproject.org. This works if the document is still in flux somewhat. Then it has an official-looking URL, and the others can mirror that.
However, if it's solid and not likely to get as many edits, then it seems to me like a perfect document for fedora.redhat.com/docs.
How about we do both? Make a permanant link for this version and stop calling it a draft - call it version 1. And another wiki version ready for any later changes?
http://fedora.redhat.com/participate/documentation-quick-start/
We can get a writer to help with the conversion to DocBook and to get the author/maintainer started. Of course, the list is here to help with ongoing learning of DocBook, writing, etc.
I would love to put it into DocBook, I've used XMLmind for DcoBook before and would love to start using am Opensource app. I'll read the quick-start guide over the weekend.
Duncan
On second thougth...
I was wondering. The suggestions we've made, like having a link on the sig, welcoming e-mail, etc. all imply the existence of *one* permanent link, and that is unique and stable. So, I believe that there should be only one version of it.
The question now comes to which form to adopt: DocBook or Wiki?
Based on maturity, since this document has gone through 4 draft versions, all discussed openly in the list, I believe it is mature enough to get the DocBook format. It would also give it a more "official" look. However, it seems to me, the DocBook is a more closed format, with more restrict access.
On the other hand, being a community born document, maybe the Wiki is more appropriate, by giving it a more open character. On the weak side, the Wiki would have less of an "official" impact.
I think both formats have their pros and cons. What's your opinion about it?
On Thu, 2005-03-31 at 22:27 -0600, Gustavo Seabra wrote:
I believe that there should be only one version of it.
I agree. You only want to maintain one source and derive all others from that.
The question now comes to which form to adopt: DocBook or Wiki?
Based on maturity, since this document has gone through 4 draft versions, all discussed openly in the list, I believe it is mature enough to get the DocBook format. It would also give it a more "official" look. However, it seems to me, the DocBook is a more closed format, with more restrict access.
What I understand you to mean is, it is harder to learn how to use and manipulate DocBook than a Wiki. That is true.
Otherwise, DocBook is the de facto standard open format for writing technical documentation.
On the other hand, being a community born document, maybe the Wiki is more appropriate, by giving it a more open character. On the weak side, the Wiki would have less of an "official" impact.
My guess is that this document will not need that many revisions. It is based on solid principles and tailored to a particular audience. A Wiki is a great collaborative tool and gives you quick and easy ways to post information. But DocBook is on a different level.
For example:
* DocBook is a single source that gives you multiple output formats -- HTML, PDF, RTF, TXT, etc.
* You can translate the strings in DocBook (the content between the tags) without having to touch the formatting. Fedora translators are used to working with DocBook.
* XML and XSL allow us to add stylesheets for other accessibility needs, such as producing a high-contrast, large-font output for visually impaired, or output for text-to-speech programs to use.
My thinking is that if a document is out of draft/beta stage and doesn't need more collaboration, we should put it into DocBook.
- Karsten
On Apr 1, 2005 2:17 AM, Karsten Wade kwade@redhat.com wrote:
On Thu, 2005-03-31 at 22:27 -0600, Gustavo Seabra wrote:
The question now comes to which form to adopt: DocBook or Wiki?
Based on maturity, since this document has gone through 4 draft versions, all discussed openly in the list, I believe it is mature enough to get the DocBook format. It would also give it a more "official" look. However, it seems to me, the DocBook is a more closed format, with more restrict access.
What I understand you to mean is, it is harder to learn how to use and manipulate DocBook than a Wiki. That is true.
Well, not really. The point isn't the difficulty, Duncan has even already volunteered to do the DocBook translation. My question is more about the /character/ of the document.
I now understand the advantages of DocBook, and it seems a wonderful tool for writing the system documentation. The question is: is it appropriate for a /mailing list guidelines/? Or would that be better written in a lighter format, but which lacks the flexibility of the DocBook? I really don't know.
On Fri, 2005-04-01 at 00:17 -0800, Karsten Wade wrote:
On Thu, 2005-03-31 at 22:27 -0600, Gustavo Seabra wrote:
I believe that there should be only one version of it.
I agree. You only want to maintain one source and derive all others from that.
Since it was probably my suggestion of a wiki version that has caused some confusion I should mention that I also agree there should only be one 'official' version. However much of my background in online writing is based on work with http://indymedia.org and their documentation project http://docs.indymedia.org . So collaborative effort is something I believe strongly in and have seen the fruits of - but I'm digressing...
The question now comes to which form to adopt: DocBook or Wiki?
Of course wiki is unsuited to an 'official' version, but is DocBook really suited, as Gustavo wonders, to an email list users guide?
I'm inclined to feel that the 'official' version should be plain ascii - after all that's what we want people to use on the list. All other forms can then be derivatives of that.
Or would it work for the 'official version to be DocBook which can generate a txt file?
hmmm, not sure myself
Duncan
On Fri, 2005-04-01 at 18:39 +0200, Duncan Lithgow wrote:
Or would it work for the 'official version to be DocBook which can generate a txt file?
Exactly. Then you can paste the text output into a Wiki without further editing and have Good Enough.
There are ways to get DocBook out of Wiki, but it's not really a two-way operation, aiui. Any document, no matter how small, can benefit from DocBook. If this document is past rapid-pace collaboration and is ready for submission here, let's put it in DocBook XML.
There is a Style Guidelines chapter coming out soon for the project Documentation Guide. We'll want to do the final edit of the Fedora-List Guidelines using that. You can do the XML conversion now, and we can do the style guide edit later.
Is there any current or wanting to be editor with some time to be the assigned editor for the Fedora-List Guidelines?
- Karsten
On Apr 1, 2005 3:09 PM, Karsten Wade kwade@redhat.com wrote:
On Fri, 2005-04-01 at 18:39 +0200, Duncan Lithgow wrote:
Or would it work for the 'official version to be DocBook which can generate a txt file?
Exactly. Then you can paste the text output into a Wiki without further editing and have Good Enough.
Great.
There are ways to get DocBook out of Wiki, but it's not really a two-way operation, aiui. Any document, no matter how small, can benefit from DocBook. If this document is past rapid-pace collaboration and is ready for submission here, let's put it in DocBook XML.
That answers my question.
I understand that Duncan volunteered to do the DocBook translation, right? That's great. If there's anything else I can do to help, just let me know.
Cheers,
On Thu, 2005-03-31 at 12:26 -0600, Gustavo Seabra wrote:
At the 'fedora-list' there has been a recent community effort to formulate a document with the "guidelines" for posting to that list. After a number of drafts and discussions, this document has reached a more mature form, and has been put in the form of a web page:
Original: http://www-personal.ksu.edu/~seabra/linux/FedoraRules.html Mirror: http://www.cwelug.org/fedora/FedoraRules.html
Wow, as list admin even I didn't know of that ;-)
Anyways, whatever is decided here, please cc us (warren/me), or just write to fedora-list-owner@redhat.com so that we can make the appropriate changes and point people to guidelines and what not
And the best way to ge tit all in, is to make it nice and easy for us. Can someone maybe get it imported into the wiki?
Give me the appropriate text, tell me what you want and I think its a great idea
On Mar 31, 2005 8:21 PM, Colin Charles byte@aeon.com.my wrote:
On Thu, 2005-03-31 at 12:26 -0600, Gustavo Seabra wrote:
At the 'fedora-list' there has been a recent community effort to formulate a document with the "guidelines" for posting to that list. After a number of drafts and discussions, this document has reached a more mature form, and has been put in the form of a web page:
Original: http://www-personal.ksu.edu/~seabra/linux/FedoraRules.html Mirror: http://www.cwelug.org/fedora/FedoraRules.html
Wow, as list admin even I didn't know of that ;-)
Wow again! I'm sorry to hear that. The point has been discussed a lot in the fedora-list. If you want to see what has been discussed, take a look at: http://marc.theaimsgroup.com/?l=fedora-list&w=2&r=1&s=draft&...
Anyways, whatever is decided here, please cc us (warren/me), or just write to fedora-list-owner@redhat.com so that we can make the appropriate changes and point people to guidelines and what not
And the best way to ge tit all in, is to make it nice and easy for us. Can someone maybe get it imported into the wiki?
Give me the appropriate text, tell me what you want and I think its a great idea
Thank you very much for your support. We will contact you directly as soon as we reach the final decision. Thanks again.