How are we going to organize different versions of documents on the website?
Option 1. By FC version, then document.
f.r.c/docs -> FC2 -> Tutorial 1 -> Tutorial 2 ... -> FC3 -> Tutorial 1 -> Tutorial 2 ...
Option 2. By document, then FC version.
f.r.c/docs -> Tutorial 1 -> FC2 -> FC3 -> Tutorial 2 -> FC2 -> FC3 ...
Option 3. Other ideas?
On Wed, 2004-09-15 at 07:05, Karsten Wade wrote:
How are we going to organize different versions of documents on the website?
Option 1. By FC version, then document.
f.r.c/docs -> FC2 -> Tutorial 1 -> Tutorial 2 ... -> FC3 -> Tutorial 1 -> Tutorial 2 ...
Option 2. By document, then FC version.
f.r.c/docs -> Tutorial 1 -> FC2 -> FC3 -> Tutorial 2 -> FC2 -> FC3 ...
Option 3. Other ideas?
I don't see why we can't have both... Two links, "Index by Core release," then organized alphabetically within each release number, and "Index by Subject," organized by release number within each tutorial. Am I missing something?
Also, it might not be a bad idea for the editorial folks to, on publication of a new tutorial, make a list of one or more questions answered by the tutorial. Those questions should be organized into a kind of FAQ, or quasi-FAQ (QFAQ?), which a reader uses to follow a link to the appropriate tutorial in the "Index by Subject," e.g.:
How do I configure update notifications? How do I keep my system updated? How do I update my system? What is up2date? What is yum?
These are all questions that would link to the update-tutorial. This list would get pretty long, but the page should be searchable simply by using the Web browser "search" function. I don't see a need to design a complicated Web interface (search engine, indexing, etc.) for this purpose. What do you think?
On Wed, 2004-09-15 at 13:39, Paul W. Frields wrote:
Option 3. Other ideas?
I don't see why we can't have both... Two links, "Index by Core release," then organized alphabetically within each release number, and "Index by Subject," organized by release number within each tutorial. Am I missing something?
Is the information available to sort by such criteria Paul? If so then yes.
Also, it might not be a bad idea for the editorial folks to, on publication of a new tutorial, make a list of one or more questions answered by the tutorial. Those questions should be organized into a kind of FAQ, or quasi-FAQ (QFAQ?), which a reader uses to follow a link to the appropriate tutorial
Speaking from fairly bitter experience. I've been criticised for 'answering the wrong question' or bad categorising, for 6 years now. Bottom line, we can't please all of the people all of the time. People seem to come at information from n different directions. Its really hard without something like a topic map to provide the differing schemas that will meet the varying needs of users. Great idea, and a list of xrefs would answer some of the questions. No problem using docbook to mark it up... The logic for it, the groupings etc, I'll leave to the group, I gave up trying to outguess people some time ago. My best solution is to use a google search of a list of pages.
On Wed, 2004-09-15 at 11:43, Dave Pawson wrote:
On Wed, 2004-09-15 at 13:39, Paul W. Frields wrote:
Option 3. Other ideas?
I don't see why we can't have both... Two links, "Index by Core release," then organized alphabetically within each release number, and "Index by Subject," organized by release number within each tutorial. Am I missing something?
Is the information available to sort by such criteria Paul? If so then yes.
I was once again using the wrong words for the right idea, sorry. I should have said "Index by Title," and *not* "Index by Subject." One would hope the name of the tutorial is in fact the subject, but perhaps it might be misleading otherwise.
On Wed, 2004-09-15 at 08:39, Paul W. Frields wrote:
On Wed, 2004-09-15 at 07:05, Karsten Wade wrote:
How are we going to organize different versions of documents on the website?
Option 1. By FC version, then document.
f.r.c/docs -> FC2 -> Tutorial 1 -> Tutorial 2 ... -> FC3 -> Tutorial 1 -> Tutorial 2 ...
Option 2. By document, then FC version.
f.r.c/docs -> Tutorial 1 -> FC2 -> FC3 -> Tutorial 2 -> FC2 -> FC3 ...
Option 3. Other ideas?
I don't see why we can't have both... Two links, "Index by Core release," then organized alphabetically within each release number, and "Index by Subject," organized by release number within each tutorial. Am I missing something?
We could do both on the Docs page, but we still need a way to organize the left navigation bar under the Docs category. Currently, all docs are listed there because there aren't that many, but it is going to get too long very soon. Sorting by version in the nav seems reasonable to me. If a tutorial is applicable to more than one version, we can list it more than once. We also need a directory structure for the URLs as well. For example, we now have docs/selinux-faq-fc2/ but it would be better to have docs/fc2/selinux-faq/ docs/fc3/selinux-faq/, which is how redhat.com/docs/ is organized.
Tammy
Also, it might not be a bad idea for the editorial folks to, on publication of a new tutorial, make a list of one or more questions answered by the tutorial. Those questions should be organized into a kind of FAQ, or quasi-FAQ (QFAQ?), which a reader uses to follow a link to the appropriate tutorial in the "Index by Subject," e.g.:
How do I configure update notifications? How do I keep my system updated? How do I update my system? What is up2date? What is yum?
These are all questions that would link to the update-tutorial. This list would get pretty long, but the page should be searchable simply by using the Web browser "search" function. I don't see a need to design a complicated Web interface (search engine, indexing, etc.) for this purpose. What do you think?
-- Paul W. Frields, RHCE
On Wed, 2004-09-15 at 16:28, Tammy Fox wrote:
On Wed, 2004-09-15 at 08:39, Paul W. Frields wrote:
On Wed, 2004-09-15 at 07:05, Karsten Wade wrote:
How are we going to organize different versions of documents on the website?
Option 1. By FC version, then document.
f.r.c/docs -> FC2 -> Tutorial 1 -> Tutorial 2 ... -> FC3 -> Tutorial 1 -> Tutorial 2 ...
Option 2. By document, then FC version.
f.r.c/docs -> Tutorial 1 -> FC2 -> FC3 -> Tutorial 2 -> FC2 -> FC3 ...
Option 3. Other ideas?
I don't see why we can't have both... Two links, "Index by Core release," then organized alphabetically within each release number, and "Index by Subject," organized by release number within each tutorial. Am I missing something?
We could do both on the Docs page, but we still need a way to organize the left navigation bar under the Docs category. Currently, all docs are listed there because there aren't that many, but it is going to get too long very soon. Sorting by version in the nav seems reasonable to me. If a tutorial is applicable to more than one version, we can list it more than once. We also need a directory structure for the URLs as well. For example, we now have docs/selinux-faq-fc2/ but it would be better to have docs/fc2/selinux-faq/ docs/fc3/selinux-faq/, which is how redhat.com/docs/ is organized.
I see your point, Tammy, but my feeling would be to opt for only two (or three) subheadings under the current "Docs" nav bar entry:
Docs by Title by FC Release [FAQ]*
*This would be that extra structure I mentioned; not really a FAQ, but an organization of questions that would link to the Title index.
With the very aggressive release schedule of Fedora Core, it wouldn't be long before the nav bar became very crowded (FC2 through FC6, anyone?). The Docs Project doesn't currently have a policy for when we won't publish documentation anymore for a release, and I'm not sure we should have one. There may be people as comfortable staying with certain releases as they were staying with, say, Red Hat Linux 7.3. I would try and leave the nav bar as generic as possible while still being useful.
I'm sure there are problems with this idea, so I welcome the inevitable holes to be shot through it! :-)
On Wed, 2004-09-15 at 15:12, Paul W. Frields wrote:
I see your point, Tammy, but my feeling would be to opt for only two (or three) subheadings under the current "Docs" nav bar entry:
Docs by Title by FC Release [FAQ]*
*This would be that extra structure I mentioned; not really a FAQ, but an organization of questions that would link to the Title index.
I.e., "by Title" expands to have a list of all documents by title in alpha order, and "by FC Release" expands to a short list of release numbers, which then expand to a set of document titles that are just part of that release?
One immediate problem I see is a maintenance nightmare. As much as we would like to have a CMS, this is currently a manual process. We need to focus on a simple structure that works, and let Google do the indexing for us. :)
With the very aggressive release schedule of Fedora Core, it wouldn't be long before the nav bar became very crowded (FC2 through FC6, anyone?). The Docs Project doesn't currently have a policy for when we won't publish documentation anymore for a release, and I'm not sure we should have one. There may be people as comfortable staying with certain releases as they were staying with, say, Red Hat Linux 7.3. I would try and leave the nav bar as generic as possible while still being useful.
It seems reasonable to hand-off maintenance on version-specific docs to the Fedora Legacy project, when the matching version of FC is handed-off.
An author could choose to continue to work on the document, but it is now under the aegis of the Legacy group, who are presumably just following the examples and rules we have set.
Just like supporting the software, we have to draw the line on how far back this project is going to support documents. We don't have the resources to support a version of FC for several years. Tying the lifecycle of our documents into the entire distro lifecycle seems like a good idea.
Just my personal pennies,
- Karsten
On Thu, 2004-09-16 at 04:17, Karsten Wade wrote:
On Wed, 2004-09-15 at 15:12, Paul W. Frields wrote:
I see your point, Tammy, but my feeling would be to opt for only two (or three) subheadings under the current "Docs" nav bar entry:
Docs by Title by FC Release [FAQ]*
*This would be that extra structure I mentioned; not really a FAQ, but an organization of questions that would link to the Title index.
I.e., "by Title" expands to have a list of all documents by title in alpha order, and "by FC Release" expands to a short list of release numbers, which then expand to a set of document titles that are just part of that release?
Yes, exactly, although by "expand" I am guessing you mean when one clicks "By Title" in the nav bar, the body of the HTML page fills with the content. I certainly wouldn't want all that in the nav bar too. I'm not sure I made that clear.
One immediate problem I see is a maintenance nightmare. As much as we would like to have a CMS, this is currently a manual process. We need to focus on a simple structure that works, and let Google do the indexing for us. :)
Ah. If Tammy has to change three or four pages manually, plus the nav bar source, every time a document is posted, that would indeed be prohibitive. I wasn't sure of the internal process. If she had scripts doing it for her, now.... :-) Would you say that a simple listing by alphabetical title should be enough -- in other words, not much different from the current page?
With the very aggressive release schedule of Fedora Core, it wouldn't be long before the nav bar became very crowded (FC2 through FC6, anyone?). The Docs Project doesn't currently have a policy for when we won't publish documentation anymore for a release, and I'm not sure we should have one. There may be people as comfortable staying with certain releases as they were staying with, say, Red Hat Linux 7.3. I would try and leave the nav bar as generic as possible while still being useful.
It seems reasonable to hand-off maintenance on version-specific docs to the Fedora Legacy project, when the matching version of FC is handed-off.
An author could choose to continue to work on the document, but it is now under the aegis of the Legacy group, who are presumably just following the examples and rules we have set.
Just like supporting the software, we have to draw the line on how far back this project is going to support documents. We don't have the resources to support a version of FC for several years. Tying the lifecycle of our documents into the entire distro lifecycle seems like a good idea.
OK, I can live with this as well. I figured that having old versions on the shelf somewhere would be a good idea. If we obsolete our documents at roughly the same rate as other handoffs to the FLP, then we should at least have a link on &FDPDOCS-URL; that points to their document repository.
It probably bears mentioning, with absolutely no ill will or offense intended, that the FLP is currently undergoing some pain trying to recruit and maintain participation. I'm sure that's no different than many other projects, and I hope they get everything sorted out satisfactorily. We might want to be prepared for the small chance that FLP is not prepared to handle maintaining any such repository. The task of storage won't be overwhelming in that case, but the task of maintenance will, of necessity, likely drop off the scope.
I think that adding 'sn-' etc. before each id is redundant. I have an article which has only sections and where all the ids start with 'sn-'. What is the reason for doing it like that? Can I ommit it?
About the names of the files: is it a convention for doing it like this: example-tutorial-en.xml? Is there any problem if I do it like this: example_tutorial_en.xml? (does it break anything, etc.)
On Tue, 2004-09-21 at 03:30, Dashamir Hoxha wrote:
I think that adding 'sn-' etc. before each id is redundant. I have an article which has only sections and where all the ids start with 'sn-'. What is the reason for doing it like that? Can I ommit it?
Yes, you can probably omit it. If you search the archive for the list you'll see a discussion regarding this topic that probably doesn't bear re-hashing.
About the names of the files: is it a convention for doing it like this: example-tutorial-en.xml? Is there any problem if I do it like this: example_tutorial_en.xml? (does it break anything, etc.)
Yes, the Makefile will break. Use "-" to simplify your life please. :-)
On Tue, 2004-09-21 at 04:25, Paul W. Frields wrote:
On Tue, 2004-09-21 at 03:30, Dashamir Hoxha wrote:
I think that adding 'sn-' etc. before each id is redundant. I have an article which has only sections and where all the ids start with 'sn-'. What is the reason for doing it like that? Can I ommit it?
Yes, you can probably omit it. If you search the archive for the list you'll see a discussion regarding this topic that probably doesn't bear re-hashing.
Yeah, I recently decided that we should make the ID tag existence and details recommended but optional.
Recommendation based on previous discussion, not worth rehashing. :)
- Karsten
Karsten Wade wrote:
On Wed, 2004-09-15 at 15:12, Paul W. Frields wrote:
I see your point, Tammy, but my feeling would be to opt for only two (or three) subheadings under the current "Docs" nav bar entry:
Docs by Title by FC Release [FAQ]*
*This would be that extra structure I mentioned; not really a FAQ, but an organization of questions that would link to the Title index.
I.e., "by Title" expands to have a list of all documents by title in alpha order, and "by FC Release" expands to a short list of release numbers, which then expand to a set of document titles that are just part of that release?
One immediate problem I see is a maintenance nightmare. As much as we would like to have a CMS, this is currently a manual process.
FWIW, if you built the site with the DocBook Website DTD & stylesheets, the expanding ToC/navbar gets generated automatically. (I wrote the dbwebsite code for that turns/expands the icons.) And the really nice thing is that the source content of the site is - you guessed it - XML:)
Doubt that the resources exist presently for a site rebuild based on the DocBook Website package, but it may be worth investigating for the long term.
Sites built from this package are ubiquitous. (Dave Pawson's is a case in point, though he uses a horizontal ToC/navbar:)
A good example of the kind of navbar/ToC expansion you're talking about is at http://docbook.org. Click on the 'schema' link on the navbar to see how the ToC expands and the icons flip to provide some visual cues as to the present navigational context.
It wouldn't be too difficult to reproduce the current Fedora site look-n-feel by customizing the website stylesheets, if someone had the time & energy to do it.
Maintaining a website by hand-coding HTML is a painful process, but 'sounds like it's the best we've got for now.
My $0.02, Mark
We need to focus on a simple structure that works, and let Google do the indexing for us. :)
On Wed, 2004-09-15 at 23:12, Paul W. Frields wrote:
I see your point, Tammy, but my feeling would be to opt for only two (or three) subheadings under the current "Docs" nav bar entry:
Docs by Title by FC Release [FAQ]*
*This would be that extra structure I mentioned; not really a FAQ, but an organization of questions that would link to the Title index.
With the very aggressive release schedule of Fedora Core, it wouldn't be long before the nav bar became very crowded (FC2 through FC6, anyone?). The Docs Project doesn't currently have a policy for when we won't publish documentation anymore for a release, and I'm not sure we should have one. There may be people as comfortable staying with certain releases as they were staying with, say, Red Hat Linux 7.3. I would try and leave the nav bar as generic as possible while still being useful.
I'm sure there are problems with this idea, so I welcome the inevitable holes to be shot through it! :-)
It struck me that Tammy was getting hung up on the left hand nav bar. The fact that it has navigability issues for accessibility isn't the only reason to question it.
A plain html list or other structure wouldn't hurt too much, and would provide the options.
On Thu, 2004-09-16 at 09:28, Dave Pawson wrote:
It struck me that Tammy was getting hung up on the left hand nav bar. The fact that it has navigability issues for accessibility isn't the only reason to question it.
A plain html list or other structure wouldn't hurt too much, and would provide the options.
Oh, I thought that the nav bar was fairly accessible, being a construct of CSS. When I've seen the page rendered without any stylesheet, the links cascade in a manner you could move through with a tab. Also, I thought the order within the HTML was roughly standardized to make it usable for a11y and handheld devices?
Thanks for the clarification, btw, a11y is an area I need more edumacation in.
- Karsten
docs@lists.stg.fedoraproject.org
-
Dashamir Hoxha -
Dave Pawson -
Karsten Wade -
Mark Johnson -
Paul W. Frields -
Tammy Fox