Skip to Content.
Sympa Menu

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

sm-discuss AT lists.ibiblio.org

Subject: Public SourceMage Discussion List

List archive

Chronological Thread  
  • From: Doubletwist <doubletwist AT spack.nu>
  • To: sm-sorcery AT lists.ibiblio.org, sm-discuss AT lists.ibiblio.org
  • Subject: [SM-Discuss] Website and Documentation for SourceMage 1.0 [longish]
  • Date: Tue, 15 Oct 2002 12:16:58 -0500

[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






Archive powered by MHonArc 2.6.24.

Top of Page