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

[Kim Lester <kim@dfusion.com.au>]

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