Re: [Phpwebsite-developers] 1.x Documentation

[Greg M. <drk...@co...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matthew McNaney wrote:
> On Wed, 2005-11-02 at 15:12 +0000, Shaun Murray wrote:
> 
> 
>>Is there some way we could have both local versions and remote versions?
> 
> 
> Yes there could be local copies of the files. I would start by writing
> my documentation. Then we could have occasional wiki exports to replace
> these files.
> 

I like this idea but I think there are issues with it.

So depending on the level of "local" documentation, the user will still
post the same FAQ question on the forum over and over again.  They may
hit the local text file before the updated wiki file.

If there is a glaring issue with the "local" file, then how long will it
be before the "local" file is fixed and a new release has the needed
change?  Moreover, how long before the user upgrades to see the change?
 Most of phpWebSite users are not going to cvs co the latest text files.

Finally, for all intents and purposes I believe those local files will
not be updated.  If Matt has to choose between publishing code or
writing documentation verses conducting an on-site training at campus,
my bets are on the code and the on-site class.  The documentation slips
another week and then month and then year and then years.  That
shouldn't be taken as bashing Matt.  I think it reflects the reality of
corporate America. Matt will work on what pays the bills.  If I felt the
local files would be updated, then wouldn't these local files be updated
http://phpwebsite.appstate.edu/manual/html/bk01.html .  Those came
out--for 0.9.3 or so?  How long has it been since the existing text
files have been updated?

I agree that it is a good idea, but I don't think it will happen.  We
don't have the Apple dollars to risk diffusing the documentation effort
between a local and remote copy of the same documentation.

> 
> 
>>With sites for non-geeks, it's been very important to provide jargon  
>>free documentation and site specific documentation to get people  
>>using a site. Although the community wiki is excellent, it's  
>>sometimes too indepth for users.
> 
> 
> I have heard that as the argument FOR using Wiki instead of local docs. 
> People have read my docs and said I make too many assumptions on the
> ability of the reader.

Part of it may be the market Matt serves.  There's a world of difference
when you can put out a text file of minimal instructions, then walk down
the hall and help the Appstate campus user design a new theme.  Matt can
make those assumptions of the user because if the user he's standing in
front of doesn't get a concept, then Matt can go install the software
for them, for example.

I don't think that the depth is an issue.  If fact I see the opposite.
The depth is too much for someone like, Wendall911, mhnoyes, or
singletrack.  However, the wiki is filling the gap that the existing
text files don't cover. I use wiki pages URLs to use in forum posts to
answer the questions that the text file does not have.  That's the whole
point behind of this page
http://phpwebsite-comm.sourceforge.net/wiki/index.php?title=User_FAQ .
Please look at the history page here
http://phpwebsite-comm.sourceforge.net/wiki/index.php?title=User+FAQ&action=history&limit=100&offset=0
.  The FAQ points back to a pin point location for the user to solve
their problem.  Text files cannot do this.  I can instantaneously refine
documentation, create diffs, update "CVS", create FAQs with the press of
a wiki save button verses learn docbook, try to get the local catalog
straight, compile it, fix the tag errors, CVS update, learn another
docbook favorable editor, perform a unified diff, submit a bug or RFE
for the txt file change....  It looks like the User FAQ page alone has
had around 100 updates between Jan 30 and Oct 30 of this year.  Most of
the text files are were last updated circa version 0.9.3.

> 
> 
>>If we could allow a local tailored  
>>copy of the docs but provide pointers to online resources that would  
>>be very useful.
> 
> 
> I guess a setting for using local docs instead of wiki. Perhaps this
> should be a per document setting?
> 
> Thanks Shaun.
> 
> Any other suggestions or additions?
> 

Perhaps one final page to make the en_* concept more concrete.  Take a
look at this page
http://phpwebsite-comm.sourceforge.net/wiki/index.php?title=Quick_Index
and imagine that is the language pages have a similar page.  This would
one would be en_*

Greg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org

iD8DBQFDawgvxyxe5L6mr7IRAoWLAJ9bYE+rl66bADHEYqTo+L/XuMcRzQCgmZlV
fwGiUHi7govT0dVYoph0eU8=
=wGtF
-----END PGP SIGNATURE-----