chunked guide - macports.org/docs/

[Ryan Schmidt]

On Jul 30, 2008, at 11:23, markd at macports.org wrote:

>> My idea was for /docs/ to be static HTML/PHP  in the repo which
>> renders to something like:
>>
>>
>> Documentation:
>> 	* Installation

We currently have a standalone page:

	http://www.macports.org/install.php

and a Guide chapter:

	http://guide.macports.org/#installing

and a Wiki page:

	http://trac.macports.org/wiki/InstallingMacPorts

Though some users may want to install trunk, for which we a separate  
how-to:

	http://trac.macports.org/wiki/howto/RunningTrunk

And also:

	http://trac.macports.org/wiki/GetMacPortsSource


>> 	* HOWTOs

The list of how-to's is in the Wiki:

	http://trac.macports.org/wiki/howto


>> 	* Guide:
>> 		* Chunked HTML
>> 		* Single HTML
>> 		* a future PDF version maybe?

Yes, that would be good. Much like the Subversion project offers many  
formats of its book; see:

	http://svnbook.org/


>> 	* FAQ

Frequently-asked questions are in the Wiki:

	http://trac.macports.org/wiki/FAQ

Though we also have the ProblemHotlist:

	http://trac.macports.org/wiki/ProblemHotlist

And LeopardProblems:

	http://trac.macports.org/wiki/LeopardProblems

All of these should probably be regrouped as just "FAQs".

And I mentioned in an earlier thread that I think it would be a good  
idea if we would have a Wiki page to describe several of the error  
messages that a user might be expected to encounter in the course of  
using MacPorts. So an "Error Messages" menu item on the docs page  
would be good.


>> 	* Bug Reporting Guidelines

We have bug reporting guidelines in the Guide:

	http://guide.macports.org/#project

And also in the Wiki:

	http://trac.macports.org/wiki/TracTicketing


>> 	* Becoming a Member??

Good idea. We currently have these documents on that topic:

	http://guide.macports.org/#project.membership

	http://trac.macports.org/wiki/NewCommittersGuide

	http://trac.macports.org/wiki/CommittersTipsAndTricks



I would also want a "how to use MacPorts" document. These documents  
describe that, though probably not completely:

	http://guide.macports.org/#using

	http://trac.macports.org/wiki/UsingMacPortsQuickStart


>> So this /docs/ page would replace several left navigation links on
>> macports.org. The existing Documentation link would point to /docs/
>> and the above list.
>
> I like this idea.  One benefit would be that it would allow us to  
> unify
> the install information (guide & website are different), which  
> needs to be
> done anyway.


I would recommend that before we create a documentation index page,  
we consolidate our documentation and not have three or four distinct  
URLs describing the same basic things. A lot of the Guide was taken  
from Wiki pages, so the Wiki pages that the Guide obsoletes should be  
cleared of their contents and replaced with a link to the appropriate  
Guide section (after ensuring that all content from the Wiki pages  
has made it into the corresponding Guide sections).


So www.macports.org/docs would list the available documentation. And  
the Guide would be where? Still at guide.macports.org? Or would it  
move to www.macports.org/guide? or www.macports.org/docs/guide? An  
advantage I think of keeping the Guide on its own hostname is that  
you can limit a Google search to just that hostname, so you get just  
Guide results. If we move the Guide to www.macports.org/whatever, can  
we still make a Google search that just searches the Guide?

The wiki would stay at trac.macports.org/wiki? Or would you want it  
to move to www.macports.org/wiki? or www.macports.org/docs/wiki? I'm  
not sure if we can or should move the wiki URL independent of the  
rest of the Trac URLs.