Skip to Content.
Sympa Menu

sm-discuss - [SM-Discuss] Re: [SM-Sorcery]Website and Documentation for SourceMage 1.0 [longish]

sm-discuss AT lists.ibiblio.org

Subject: Public SourceMage Discussion List

List archive

Chronological Thread  
  • From: Dufflebunk <dufflebunk AT dufflebunk.homeip.net>
  • To: Doubletwist <doubletwist AT spack.nu>
  • Cc: sm-discuss AT lists.ibiblio.org
  • Subject: [SM-Discuss] Re: [SM-Sorcery]Website and Documentation for SourceMage 1.0 [longish]
  • Date: 15 Oct 2002 16:18:13 -0400

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




Archive powered by MHonArc 2.6.24.

Top of Page