Dave Johnson wrote:
On 6/8/06, Allen Gilliland <[EMAIL PROTECTED]> wrote:
Dave Johnson wrote:
>> docs/*
>
> I strongly object to removing the docs from the webapp. The docs for
> the current version of the app should be made available within the
> app. The should be moved to roller-ui so they are not polluting the
> URL space.
I am fine with that. In general I think the issue with docs is a coin
flip for me. On one hand I definitely see the benefits of including the
docs in a browsable location of the app with each release. However, on
the flip side there is something to be said for not polluting the webapp
with things that people don't really need, we can package the docs in
the bundle and not in the webapp and if people want to move them into
the app then they can do so. there is also something to be said for
maintaining online documentation in a central location like
roller.apache.org/docs and not duplicating those docs over and over
again.
It's a lot easier for the user to simply click on the docs link and see the
user guide than it is for them to go to our website and search around for
the docs that correspond to the version of Roller that they are using.
I think we may be talking about 2 slightly different types of
documentation. I see 2 types ...
1. Admin documentation. Stuff about how to setup/upgrade Roller, info
about change logs and versions, etc. Basically, all the documentation a
Roller blogger doesn't necessarily care about.
2. User documentation. Stuff about how to use Roller, macro guides,
tips on template customizations, plugins/editors help, etc. Stuff that
any user may want access to.
In my opinion it doesn't make any sense for #1 to be inside the
application. Those docs are really only meant for the person installing
/maintaining the site and are meant to be read before the app is installed.
I think it's fine if the User docs are inside the app. I don't think it
has to be, but I can see this being convenient.
i consider the "release" and the
"webapp" to be 2 different things. the webapp is just what gets run in
the container, i.e. what you get in build/roller. the release is the
webapp plus whatever else we think is useful, typically like legal
notices, docs, examples, plugins/addons, etc.
Right now we just ship two things 1) the self contained webapp and
2) the source release. To run Roller all you need is #1. I don't see a
compelling reason to change that yet. Plus, I believe that docs and
license/notices should be embedded in the app.
I see. Well, my opinion is that's kinda "eh". I prefer a more standard
bundle for a number of reasons ...
1. It's 100% essential that we start marking releases with version
numbers. When you tar/gzip the package it should come out in a
directory such as roller-x.y.z.
2. As we have been discussing there are certainly things that belong in
the downloadable package but not in the webapp itself.
3. Eventually we should package as a .war file and not just a directory
tree for the app, and in that case it makes more sense to have an actual
bundle with the .war included, rather than making the .war the only
distribution.
4. Using a bundle gives us much more flexibility to include other things
that may be useful to the user, but which shouldn't really be directly
included in the core webapp. themes? plugins? editors?
I don't really think it's ideal to only package the webapp for the
release and then end up having to put things in the webapp which
shouldn't be there so that that they are in the download. It's not that
hard to setup a very simple structure for the download bundle and make
it part of the build process. I am more than willing to do this.
-- Allen
- Dave
