chunked guide - macports.org/docs/
ryandesign at macports.org
Thu Jul 31 00:46:41 PDT 2008
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:
>> * Installation
We currently have a standalone page:
and a Guide chapter:
and a Wiki page:
Though some users may want to install trunk, for which we a separate
>> * HOWTOs
The list of how-to's is in the Wiki:
>> * 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:
>> * FAQ
Frequently-asked questions are in the Wiki:
Though we also have the ProblemHotlist:
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:
And also in the Wiki:
>> * Becoming a Member??
Good idea. We currently have these documents on that topic:
I would also want a "how to use MacPorts" document. These documents
describe that, though probably not completely:
>> 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
> 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.
More information about the macports-dev