[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: HOWTO vs mini-HOWTO [was: Linux Doc Infrastructure]

Morten Kjeldgaard wrote:
> 
> >
> > What about a 3 weeks poll where each author can vote :
> >  1/ Merge the mini HOWTOs with the HOWTOs
> >  2/ Keep the HOWTOs and the mini HOWTOs separated
> >  3/ blank
> 
> Sounds good to me. However, to make peoples decision more enlightened
> perhaps it would be good with a proof-of-concept. Would it be possible to
> delay the poll until such a thing is available? I am willing to pitch in,
> (reorganizing the EXISTING [mini-]?HOWTO documents in a tree structure)
> but since I am also busy with other things, I cannot do it all alone.
> Anyone else?
> 
> /Morten


OK, well I've also got other things to do but I'd like to try and
help reorganise the HOWTOs.
I'll say in advance that my solution would probably involve several
newish aspects (if people think this is bad please comment now):

  * cutting a number of them up (which cover >1 topic)
  * where docs fall into several categories create a master HTML
        document for each category which points at all the bits
        to form a smooth logic flow.

I'll also admit that it was partly the HOWTOs that catalysed the
ode-discuss list into existence, so I'd be interested in making a
simple test case of at least some of the HOWTOs. Nothing too
complex mind you.

I'd suggest the network howtos are proably the best example
to restructure. BTW I think the existing doc contents are
_great_ so don't anyone think I'm complaing out that.
The internal structure of some of the latest is also good.

What I'm saying is that "Networking" is currently made up of
roughly the following:
        DNS-
        Ethernet-
        Firewall-
        Hardware-
        IPCHAINS-
        IPX-
        IR-
        ISP-Hookup
        Modem-
        Multicast
        NET-3
        NET3-4
        PPP-
        SMB-
        UUCP-
        Unix-Internet-Fundametnals
        VPN-Masquerade
        WWW-
        
        mini/
                Bridge
                Bridge+Firewall
                Cable-Modem
                Cipe+Masq
                DHCP
                DHCPcd
                Diald
                Firewall-Piercing
                IP-Alias
                IP-Masquerade
                IP-Subnetting
                ISP-Connectivity
                Proxy-ARP-Subnet
                Term-Firewall
                Token-Ring
                Windows-Modem-Sharing

 I didn't realise there were so many!!
And this doesn't include any distribution/windowing enviornoment
specific differences.

 Now in advance I accept that some of you might have a slighly
different list, but even if you crossed half of the above off
I still get to make my point.

Now you and I, being experienced, don't have a great problem
picking out the relevant docs.
You might also say that if you don't understand what a Bridge is
you wouldn't want to look at that doc. But for example you
might need some form of PC connectivity, both DHCP and SMB etc
could be relevant, not obvious.

We thus need to provide a contents/index doc that guides
a person though the documents. This also implies cutting up
some of the docs as chunks are repeated.

Come to think of it this is so "important" I might try doing
it myself anyway, but would LDP accept the results ??

OK everyone now it's your turn to tell me I've got it all wrong :-)

cheers
                Kim


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org