PDA

View Full Version : OJP Documentation Improvements Thread


razorace
03-22-2007, 02:52 PM
I'm starting up this thread to get some feedback on how we can improve the OJP documentation to make it more user-friendly.

We're already in the process of converting everything to html, but beyond that I'm not sure what we should do.

One idea is to dramatically reducing the amount of information that is in the changelog. Should we condense the changelog so it only discusses mentions major new features and major fixes? What about the nitty gritty change details? Do people care about that stuff or should only coders know when I've changed the FP cost of kicks from 2 to 3?

What do you guys think?

HamstrYODA
03-22-2007, 04:50 PM
I think that changelog needs only major features and fixes what comes to older version. maybe every detail for newest version (what has changed from last version to new one) and major things for older versions. If it isn't too much work to remove all minor things from changelog when next version comes out. (i hope you understand what i mean, my english fails sometimes)

on the other hand, does it matter if there is all the information... I think most of people doesn't even open the changelog. People who read it are interested about it and may want to know every change.

bah. first i had idea but when i kept writing and thinking, now i dont know is it good idea :p

ensiform
03-22-2007, 05:43 PM
I think we should have a text changelog like so for server:
http://linespeed.net/projects/etpub/browser/trunk/ChangeLog.txt?format=txt
And client/ui:
http://linespeed.net/projects/etpub/browser/trunk/ChangeLog-client.txt?format=txt

And an overall documentations like so:
http://linespeed.net/projects/etpub/browser/trunk/docs/index.html?format=raw

http://linespeed.net/projects/etpub/browser/trunk/docs/index_pub.html?format=raw

Mantis01
03-23-2007, 01:03 AM
I'm starting up this thread to get some feedback on how we can improve the OJP documentation to make it more user-friendly.

We're already in the process of converting everything to html, but beyond that I'm not sure what we should do.

One idea is to dramatically reducing the amount of information that is in the changelog. Should we condense the changelog so it only discusses mentions major new features and major fixes? What about the nitty gritty change details? Do people care about that stuff or should only coders know when I've changed the FP cost of kicks from 2 to 3?

What do you guys think?

following are my opinion.

In high priority,
For novice users, our OJP document should include more clear difference from "original JKA" to "latest OJP".
(A present document has only latest changelog)
following proposal of elements,
- OJP concept
- Saber combat manual
- Experience system
- Mercenaries
- Source build manual
- ToDo(target in the future)

And of course, latest changelog is needed for veteran user.
I welcome web-based document.
It is necessary to always contain the latest specification in an online
document.

In low priority,
we should correspond to multi languages ??
Yes, I will prepare a Japanese document.

These are trifling opinion from me.:)

Maxstate
03-23-2007, 07:03 AM
I think we should have a text changelog like so for server:
http://linespeed.net/projects/etpub/browser/trunk/ChangeLog.txt?format=txt
And client/ui:
http://linespeed.net/projects/etpub/browser/trunk/ChangeLog-client.txt?format=txt

And an overall documentations like so:
http://linespeed.net/projects/etpub/browser/trunk/docs/index.html?format=raw

http://linespeed.net/projects/etpub/browser/trunk/docs/index_pub.html?format=raw

I actually converted most of the OJP documentation to HTML the hard way and it looked something like that, but Razor didn't like it :(

I think Mantis has the right idea though, we need to state the differences between regular JKA and OJP clearly.

razorace
03-23-2007, 02:10 PM
I think Mantis has the right idea though, we need to state the differences between regular JKA and OJP clearly.
I'm open to suggestions. The current readme already covers the OJP concept in some detail, but it's apprenently too complicated or never read by users.

madcatmach2
03-23-2007, 03:49 PM
I think we should have a text changelog like so for server:
http://linespeed.net/projects/etpub/browser/trunk/ChangeLog.txt?format=txt
And client/ui:
http://linespeed.net/projects/etpub/browser/trunk/ChangeLog-client.txt?format=txt

And an overall documentations like so:
http://linespeed.net/projects/etpub/browser/trunk/docs/index.html?format=raw

http://linespeed.net/projects/etpub/browser/trunk/docs/index_pub.html?format=raw
that deffinetly git's my vote that and i love the kinks to skip right to the part i want like say the saber section for new people

Maxstate
03-24-2007, 05:18 AM
I'm open to suggestions. The current readme already covers the OJP concept in some detail, but it's apprenently too complicated or never read by users.
You just need to pull that American movie announcer thing:
This summer... The Open Jedi Project will rock the internets!
A completely new movielike sabersystem that features parrying, faking, riposting and power attacking, expanded Force powers that'll make you cream your pants, new gamemodes like Cooperation mode and much much more.

:p

People just want a short description of a feature so they can decide if the mod is worth their download. When I was still modhunting for JKA I would cruise through www.jk3files.com and just shortly read the description, if it said things like ^^^^^ that I would download it in a second.

razorace
03-26-2007, 07:31 PM
Got a WIP version of the new documentation on the repository. Check it out and see what you think.

Readme (https://opensvn.csie.org/traccgi/ojp/browser/Basic/docs/OJP_Index.html?format=raw)
Index (https://opensvn.csie.org/traccgi/ojp/browser/Basic/docs/OJP_Readme.html?format=raw)

FYI, this is the latest repository version, so it will be updated as I work on it.

EDIT: Updated to FireFox compatible links.

ensiform
03-27-2007, 05:51 PM
FYI:
Index (https://opensvn.csie.org/traccgi/ojp/browser/Basic/docs/OJP_Index.html?format=raw)
Readme (https://opensvn.csie.org/traccgi/ojp/browser/Basic/docs/OJP_Readme.html?format=raw)

razorace
03-27-2007, 06:27 PM
Ah, gotcha. Thanks Ensi.