Public SourceMage Discussion List

[Dufflebunk <dufflebunk AT dufflebunk.homeip.net>]

Does this mean that you are volunteering for the position of
Documentation Guru?

On Tue, 2002-10-15 at 13:16, Doubletwist wrote:
> [Please reply to the list, my email is down temporarily]
> 
> As we head towards a release of SourceMage 1.0, I think we need to take 
> a serious look at the website and documentation. It has served us well 
> during development, but the site is not at all ready for use as a public 
> front to our newly released distribution. Here are some things I think 
> need to be dealt with before our 1.0 release.
> 
> 
> 1. Documentation: This is of PRIME importance!!!!
> a. First of all, where is it? The info in the Wiki [I'll talk about that 
> later] is mostly out of date, very slim on real information, and often 
> written as a "well, this is how I did it". We can obviously use these 
> existing items as a base to start, but I don't think they should be our 
> final documentation for 1.0, especially as much of it was written 
> shortly after we changed our name.
> b. While its good that everyone can contribute, I think we need a 
> documentation guru [much like the grimoire gurus] to check submitted 
> documentation, make sure it fits a common format, to check accuracy and 
> readability, and to keep documentation up-to-date as SourceMage changes.
> c. We need at the very minimum, official documentation for:
> i. A FAQ  actually our current FAQ is pretty good ;)
> ii. Getting SourceMage
> 1. Requirements
> 2. Getting the ISO
> iii. Installing SourceMage
> iv. Using SourceMage
> d. Once we have that, we can work on more advanced documentation for 
> things like:
> i. Spell Writing Handbook
> ii. Grimoire Guru Handbook
> iii. HOWTOs
> iv. Developer and contribution information
> v. Etc&
> 2. The Website: As the main source of information the layout and content 
> needs to be changed.
> a. Front Page: The front page is the first thing people are going to see 
> when they want to find out about our distro, so it needs to be designed 
> with that in mind. I know its a horrible cliché, but there really is no 
> second chance to make a first impression. Thats definitely true for web 
> pages.
> i. Font size  the text size for the links is small and hard to read. It 
> needs to be a bit bigger
> ii. Theres no link to Documentation!!!! Yeah theres a link to the 
> wiki, but the users arent going to know that thats where we keep our 
> documentation.
> b. Information: The links you get by clicking on Information should be 
> the same as the links listed underneath it.
> i. About SourceMage:
> 1. Social Contract: - OK
> 2. Constitution  either we need to have one, or kill the link to it.
> 3. The Team  Either make the new team database, or leave the link 
> pointing to the old org chart
> 4. Our History - OK
> ii. How to Help 
> 1. What we need  either put something, or dont have a link to it
> 2. Join the Team  either put something or dont have a link to it
> 3. Donate  ok
> 4. Sponsor Us  either have some info or dont have a link to it
> 5. Contact Us  OK
> c. Tools: Perhaps this should be changed to Developer Tools or 
> something. Since other than the Wiki its all things for the SourceMage 
> developers to use. Maybe make a User Tools section for user stuff.
> i. Bugzilla  OK
> ii. The Wiki  Ok, this is a tough one. As I said, it has worked well 
> for the development of everything to this point, but I really dont feel 
> its a good way to do official documentation. Its way too easy for 
> someone to make a small change in some documentation that will totally 
> kill someones box if they follow it. It also leaves thinks looking 
> unprofessional.
> 1. It might still be a good idea to keep the Wiki as someplace for users 
> to post tips on various aspects of installing and using SourceMage.
> iii. The Codex  OK  IF its listed under a developer tools section. 
> Otherwise most users wont know what the heck the Codex is, in which 
> case it should perhaps be linked in the Get SourceMage section
> iv. Browse the Source  OK if listed under developer tools, otherwise 
> it should maybe be linked in the Get SourceMage section.
> d. Resources:
> i. Mailing Lists  This section is fine as it is.
> ii. Forums  Ugh! I dont know about this one. Certainly at the moment 
> it is a detriment to the site. No one uses them, and for a 1.0 release, 
> new users might be put off by that fact. Also the Poll hasnt been 
> changed since the First Poll was put up 5 months ago or so. I think we 
> are better off sticking to the mailing lists.
> iii. Contact Us  Ok, good info here already.
> 
> 
> So thats all I can think of right now. Obviously I havent thought of 
> everything, so this is far from a perfect setup, but I think it will be 
> much better than what we currently have. I'm not just complaining here, 
> I'm more than willing to help out. As a matter of fact, I was starting 
> some documentation on spell writing, but I'm going to put that on hold 
> and concentrate on some documentation for new users [getting, installing 
> and using sourcemage]
> Also, Im believe right now that Ryan Abrams [flipsidejones], our 
> fearless leader, set up the website. I think that since hes obviously 
> very busy getting SourceMage ready for its release, someone should be 
> put in charge of the website that has more time to devote to keeping it 
> up to date.
> 
> Ok, so thats a LOT more than my 2 cents& J
> 
> Doubletwist
> 
> 
> _______________________________________________
> SM-Sorcery mailing list
> SM-Sorcery AT lists.ibiblio.org
> http://lists.ibiblio.org/mailman/listinfo/sm-sorcery
-- 


Quidquid latine dictum sit, altum sonatur. 
-----------------
PGP public key at
http://wwwkeys.pgp.net:11371/pks/lookup?op=get&search=0x3327A9A5
F1

Attachment: signature.asc
Description: This is a digitally signed message part