Website & documentation updates

[Juan Manuel Palacios]

	Hello documentation team! (and, of course, anyone else who wants to  
lend a hand for the heavy lifting ;-)

	First off, I would like to apologize for having disappeared for the  
last couple of weeks, that annoying "real life & work" thing hasn't  
left me with much extra time lately to work with you guys ;-) I hope  
I can still mull your interest to work on a little reorganization of  
our documentation priorities.

	As you may have seen in r29593, I recently committed a facelift to  
the MacPorts installation instructions in the new 'install.php' page  
(following some suggestions on this list), revamped & renamed from  
the old 'getmp.php' page. It has come to my attention, though (as  
some of you have already pointed out), that we are chronically and  
needlessly duplicating information all over the place (web pages,  
guide, wiki, in-source text files, etc), so I wanted to call on the  
doc team's initiative to stop this practice and centralize everything  
in a single location. The in-this-case relevant examples are a) the  
content of the new 'install.php' page and Chapter 1 of the new guide,  
and b) the overall contents of our Wiki (particularly the main page,  
http://trac.macports.org/) and Chapter 2 of the new guide. I am aware  
we're currently facing this situation simply because for a long time  
we lacked a coordinated documentation strategy, but I think it's time  
we put a stop & fix to this practice.

	We have been advancing rather slow on our new documentation and  
website efforts so far, unfortunately, so I would like to call for a  
small reorganization of our priorities by pulling a  
Steve&iPhone&Leopard move ;-) I wanted to ask you guys if it's  
possible for you to momentarily re-focus your energies into helping  
me complete the content of the new website before continuing on the  
new guide, so that we can finally provide a friendly project portal  
to newcomers ASAP.

	What I committed to 'install.php' is basically a) what was in the  
old 'getmp.php' page, plus b) some suggestions taken from this list  
(Ryan's and Chris', IIRC), and c) hints taken from the wiki doc  
"InstallingMacPorts". I believe we should reorganize these three  
sources by first taking from the wiki doc what's useful and then  
obliterating it, following with a reduction of 'install.php' to some  
smart cues that lead users in smart ways into specific sections of  
the new guide (where content from the other two sources should be  
concentrated). Any one up to the plate for this?

	Secondly, we need to start enforcing wiki documentation rules:  
HOTOWs like "Installing GNOME with MacPorts", "Setting up a MySQL &  
PHP server with MacPorts", FAQs, members' pages, etc., but no  
"official" MacPorts installation/usage/troubleshooting/membership/ 
ticketing guides and/or documents -- those belong in the *official*  
(new) guide. Our trac entry page (http://trac.macports.org/projects/ 
macports, which maps to http://trac.macports.org/projects/macports/ 
wiki/WikiStart) currently holds the following titles (next to which  
you'll find my thoughts on each):

1) http://trac.macports.org/projects/macports/wiki/InstallingMacPorts  
-- integrate into 'install.php' & chapter 1 of the guide and obliterate;
2) http://trac.macports.org/projects/macports/wiki/ 
UsingMacPortsQuickStart -- integrate into chapter 2 of the guide and  
obliterate;
3) http://trac.macports.org/projects/macports/wiki/GetMacPortsSource  
-- integrate into 'install.php' & chapter 1 of the guide and obliterate;
4) http://trac.macports.org/projects/macports/wiki/NewCommittersGuide  
-- integrate into the new guide (chapter 7?) and obliterate;
5) http://trac.macports.org/projects/macports/wiki/FAQ -- should  
remain in the Wiki, I believe (and properly advertised on the wiki's  
front page --as it now is--, in 'install.php' and in the guide);
6) http://trac.macports.org/projects/macports/wiki/BuildPhases --  
integrate into the new guide, not too sure where, and obliterate;
7) http://trac.macports.org/projects/macports/wiki/GNOME -- perfect  
example of what Wiki docs should be for, just like the FAQ;
8) http://trac.macports.org/projects/macports/wiki/TracGuide -- a  
Trac default document, should remain in the Wiki's front page;
9) http://trac.macports.org/projects/macports/wiki/ProblemHotlist --  
totally Wiki document;
10) http://trac.macports.org/projects/macports/wiki/TracTicketing --  
this one and NewTracTicketing should be merged into the new guide  
(mostly done, see ticket #12714) and then obliterated;
11) http://trac.macports.org/projects/macports/wiki/MailingLists --  
moved to the guide and obliterated.

	The result of these moves doesn't necessarily have to be a scant  
introductory Wiki page, as we can always link to the relevant guide  
pages (and whatever else we find appropriate) off it (thus favoring  
doc centralization again).

	After that's done, the only thing keeping us from going live with  
the new website would be a new "Home" section, 'index.php', per the  
guidelines I outlined for it in an earlier thread on this list:

-) Home: a front page detailing what the project is about (including  
a brief description of our ports tree), mission goals (very brief  
summary of a project roadmap) and introductory text of how to  
participate/join. Blog functionality would be provided by our  
existing Wordpress installation, but a way to smoothly tie the latter  
into the former has to be thought out.

	Of course, feel free to brainstorm over that if you have other/ 
better ideas. Anyone willing to help writing that text?

	The rest of the pending tasks for a fully functional site are mostly  
server related issues that I would have to work out with Mac OS Forge  
admin personnel. But that shouldn't stop us from moving forward as  
soon as we have the content ready, as we can always roll in new  
functionality incrementally.

	So.... this is just another one of my a-tad-too-long mails, so I'm  
gonna wrap it up here hoping you don't get too bored reading and  
instead step forward to volunteer some much needed help ;-) Thanks in  
advance!

	Regards,....


-jmpp