RE: [Mingw-users] Wiki Restructuring

[Keith M. <kei...@to...>]

Julien Lecomte wrote:
> The problem before the change is that the HOWTOs, tutorials
> and simple Q/A HOWTOs were mixed together. I remember that to
> find answers to problems I would usually click each link to open
> it in a new tab.  I do realize that the problem now is that the
> FAQ seems bloated. I did (and still do) however plan to unbloat
> down to a minimum.

The problem, from my POV, is not so much that the FAQ is bloated,
but rather that I don't think a FAQ is the most intuitive point of
reference from which to locate a HOWTO, or for that matter, a
tutorial.

Note that I would make a distinction between a HOWTO and a tutorial:
the former is essentially a reference document, and its language will
normally be much terser than that of a tutorial, which, since it is
essentially a teaching document, needs to be more verbose in its
explanation of *why* things are done the way they are.

> I think that the first step to be able to make the FAQ more usable
> would be to create a table of contents (TOC).

That would be good...

> Unfortunatly, I haven't found a way to create html anchors with
> the wiki.

I don't know either.  Perhaps there is someone out there, who can
give us a clue?

> If instead, we just have a TOC with a new page for each link,
> we'll almost end up with the same problem as before (that is a Q/A
> page with just one line of text).

Well, what we'd actually end up with is a separate page for each Q&A
couplet, but perhaps that is what you meant anyway.  I fully agree
that we don't want that!

> Another thing I plan to do to ease browsing is more cross-linking.
> For example, how to build a mingw x-compiler for linux should be
> avaible from both MinGW description page and FAQ (or HOWTO)

That's basically what I'm asking for.

>> By all means keep links to relevant HOWTOs, where 
>> appropriate, on the FAQ page, but also, let's please have a 
>> direct link on the Main Page, pointing to a catalogue of 
>> available HOWTO documents,
>
> This may seem a bit picky, but I do find that "Tutorials" might be
> a better choice for an extra entry on the HomePage. The problem with
> "HowTo" is that we end up with one line Q/A that better belong to the
> FAQ (ie, how to start a shell ? ...)

I don't agree.  As I said above, I think Tutorials and HOWTOs are two
distinct classes of document, but neither really fits the Q&A style
document model of a FAQ.  Furthermore, each Tutorial or HOWTO should
be sufficiently complete and self-contained to stand alone, and
therefore merit its own individual page.

> Otherwise, I still think that the HomePage should have a minimum of
> links, otherwise the website branches too quickly in too many 
directions,
> and make[s] finding information more difficult. Adding Tutorials could
> be good, but we shouldn't really add any more than that.

So, let's try it with one extra link on the HomePage, call it say
"HOWTOs and Tutorials".  Point that at a table of contents page, with a
one line subject reference for each document, which itself provides the
link to the actual document; this TOC linkage model should work for this
type of document, where it may not within a simple FAQ page.

> If I understand it the same way as you do: FAQ just points to Q&As with
> answers below question[s]

Yes.

> but any lengthly Q&A or tutorial should rather belong to Tutorials/HowTo
> page with answers of different page, right ?

If by this, you mean that when a question on the FAQ page requires a very
long answer, which may be better be provided by a separate tutorial or
HOWTO, then yes, a brief answer, maybe simply stating that the subject is
covered by "Such and Such Tutorial/HOWTO", should be provided in the FAQ,
with a link to the appropriate tutorial or HOWTO page.  Otherwise, IMHO
Tutorials and HOWTOs should simply be referenced from a table of contents
page, with a direct link to the TOC from the HomePage.

> Any tutorials that has as a subject a particular package should also
> be referenced from the latter package page.

Yes.

> I will deeply appreciate any help with reorganizing the wiki and
> improving it.

I'll see what I can do, as time permits.

Best regards,
Keith.