You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Igor Galić <i....@brainsware.org> on 2010/10/23 03:08:51 UTC
ASF CMS: Site and Documentation
Hi folks,
In the next two weeks I'll try to migrate trafficserver's
documentation to the ASF CMS.
http://www.staging.apache.org/dev/cms.html
For this reason I will create a branch in site:
/site/branches/ats-cms
And populate it ``by hand'', rather than trying to
convert an svn copy in place.
We should soon see how it flies!
Bye,
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: ASF CMS: Site and Documentation
Posted by "ming.zym@gmail.com" <mi...@gmail.com>.
Great if you can help consider how to do localized document management,
we are close to finish the Admin Guide translating to Chinese, we don't
want to manage a outdated translation anyway :D
thanks
在 2010-10-23六的 01:08 +0000，Igor Galić写道：
> Hi folks,
>
> In the next two weeks I'll try to migrate trafficserver's
> documentation to the ASF CMS.
>
> http://www.staging.apache.org/dev/cms.html
>
> For this reason I will create a branch in site:
>
> /site/branches/ats-cms
>
> And populate it ``by hand'', rather than trying to
> convert an svn copy in place.
>
> We should soon see how it flies!
>
> Bye,
> i
>
Re: ASF CMS: Site and Documentation
Posted by Wyn Williams <he...@gmail.com>.
Hey
Sorry to butt in but why do you not just use Plone 4 ? massively fast,
and it can do pretty much anything you need, it has many built in
functions and a great document centre + the possibility to export in
many formats and is multi-lingual with a straight forward side by side
translation system called Lingua Plone.
'
Peace
Wyn Williams
PS I will happily give it space on one of Devaus's clusters for free,
ATS is well worth it
On Mon, 2010-10-25 at 17:36 -0600, Leif Hedstrom wrote:
> On 10/25/2010 10:41 AM, Miles Libbey wrote:
> >
> > ie, Docbook? (Shutters) It is the 'industry standard', but, it would imply that we'll have some transformation scripts to produce both the
>
> I don't know, the experts in the community should decide / work on this :).
>
> > HTML and PDFs. Docbook is just XML, so, its more strict than HTML, but there are not many free docbook tools and IMHO don't hide the complexity very well. Regardless, I'm not opposed to tossing the current documentation setup, but, I think we need to be quite clear on the problems we are trying to solve, and make sure the new stuff will really solve them.
> >
> > One problem we'll eventually need to solve is how to do translations. No matter what code the documentation is written in, I don't think that's going to be easily done.
>
> I totally forgot about that. Yes, this is absolutely a requirement going
> forward with any 'rewrite' of the docs system. I know some people have
> already completed a chinese version of the docs, yet we have no way of
> "incorporating" this easily at least. Not to mention how to deal with
> incremental updates to the docs (how will a translation owner know that
> a particular piece in the english document has changed?).
>
> Cheers,
>
> -- Leif
>
Re: ASF CMS: Site and Documentation
Posted by Leif Hedstrom <zw...@apache.org>.
On 10/25/2010 10:41 AM, Miles Libbey wrote:
>
> ie, Docbook? (Shutters) It is the 'industry standard', but, it would imply that we'll have some transformation scripts to produce both the
I don't know, the experts in the community should decide / work on this :).
> HTML and PDFs. Docbook is just XML, so, its more strict than HTML, but there are not many free docbook tools and IMHO don't hide the complexity very well. Regardless, I'm not opposed to tossing the current documentation setup, but, I think we need to be quite clear on the problems we are trying to solve, and make sure the new stuff will really solve them.
>
> One problem we'll eventually need to solve is how to do translations. No matter what code the documentation is written in, I don't think that's going to be easily done.
I totally forgot about that. Yes, this is absolutely a requirement going
forward with any 'rewrite' of the docs system. I know some people have
already completed a chinese version of the docs, yet we have no way of
"incorporating" this easily at least. Not to mention how to deal with
incremental updates to the docs (how will a translation owner know that
a particular piece in the english document has changed?).
Cheers,
-- Leif
Re: ASF CMS: Site and Documentation
Posted by Igor Galić <i....@brainsware.org>.
----- Miles Libbey <ml...@apache.org> wrote:
>
> On Oct 23, 2010, at 10:22 AM, Leif Hedstrom wrote:
>
> > On 10/23/2010 09:09 AM, Miles Libbey wrote:
> >> What problems are we trying to solve by this effort? Do you envision this replacing the cwiki, the documentation (Administrator and SDK Guides), the site (http://trafficserver.apache.org/), or some combination?
> >
> > My personal view of "importance" here would be
> >
> > 1) Documentation (particularly SDK, but also Admin Guide). It's unwieldy
> > to manage I think. I think a requirement in a "rewrite" of this is that
> > it can produce documentations in some easily printable or distributable
> > format (e.g. as a PDF file).
>
> ie, Docbook? (Shutters) It is the 'industry standard', but, it would imply that we'll have some transformation scripts to produce both the HTML and PDFs. Docbook is just XML, so, its more strict than HTML, but there are not many free docbook tools and IMHO don't hide the complexity very well. Regardless, I'm not opposed to tossing the current documentation setup, but, I think we need to be quite clear on the problems we are trying to solve, and make sure the new stuff will really solve them.
>
Miles, I' not a particularily big friend of XML either. I'm not trying to throw everything we have right now. I'm trying to make it more accessible.
> One problem we'll eventually need to solve is how to do translations. No matter what code the documentation is written in, I don't think that's going to be easily done.
markdown can be easily converted in multitude of formats, PDF being one of them.
The definite advantage, IMO over both XML and HTML is that you can concentrate on the content and that even people with no love for or knolege of these formats can easily contribute fixes.
I haven't had the time today to bug joes, but for translations I'm imagining a format similar to the httpd docs. This can be taken over regardless of the format:
index.html.en
index.html.ch
index.html.jp
this can then be served via Options +MultiViews
What we need to work out is how users will switch between languages for themselves.
> miles
>
> > 2) Web site. This pretty much works as is IMO, and unless we get to the
> > point where we add more content, I see little value in changing the web
> > site right now. However, I think we need to get better at promoting some
> > of the "drafts" out of the CWiki, and turn it into real pages on the Web
> > site. This way, we can use the CWiki as the day to day work space, and
> > the web site for all the 'released' official statements and documents
> > (e.g. release plans etc.). This would also make a nicer user experience,
> > making the Web site the "one stop shop" for all relevant Apache TS
> > information.
> >
> > 3) CWiki. You'll have to make a really (*really*) hard sell to get rid
> > of the CWiki. I'm not a huge Confluence fan, but I'm even less of fan
> > of 'static content' web site / Wikis. It just simply makes no sense to
> > me personally, and there are so many advanced CMS'es that could be used
> > and would be "fast enough" (particularly if you put a web cache in front
> > of them).
> >
> > Just my $.01,
> >
> > -- Leif
> >
>
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: ASF CMS: Site and Documentation
Posted by Miles Libbey <ml...@apache.org>.
On Oct 23, 2010, at 10:22 AM, Leif Hedstrom wrote:
> On 10/23/2010 09:09 AM, Miles Libbey wrote:
>> What problems are we trying to solve by this effort? Do you envision this replacing the cwiki, the documentation (Administrator and SDK Guides), the site (http://trafficserver.apache.org/), or some combination?
>
> My personal view of "importance" here would be
>
> 1) Documentation (particularly SDK, but also Admin Guide). It's unwieldy
> to manage I think. I think a requirement in a "rewrite" of this is that
> it can produce documentations in some easily printable or distributable
> format (e.g. as a PDF file).
ie, Docbook? (Shutters) It is the 'industry standard', but, it would imply that we'll have some transformation scripts to produce both the HTML and PDFs. Docbook is just XML, so, its more strict than HTML, but there are not many free docbook tools and IMHO don't hide the complexity very well. Regardless, I'm not opposed to tossing the current documentation setup, but, I think we need to be quite clear on the problems we are trying to solve, and make sure the new stuff will really solve them.
One problem we'll eventually need to solve is how to do translations. No matter what code the documentation is written in, I don't think that's going to be easily done.
miles
> 2) Web site. This pretty much works as is IMO, and unless we get to the
> point where we add more content, I see little value in changing the web
> site right now. However, I think we need to get better at promoting some
> of the "drafts" out of the CWiki, and turn it into real pages on the Web
> site. This way, we can use the CWiki as the day to day work space, and
> the web site for all the 'released' official statements and documents
> (e.g. release plans etc.). This would also make a nicer user experience,
> making the Web site the "one stop shop" for all relevant Apache TS
> information.
>
> 3) CWiki. You'll have to make a really (*really*) hard sell to get rid
> of the CWiki. I'm not a huge Confluence fan, but I'm even less of fan
> of 'static content' web site / Wikis. It just simply makes no sense to
> me personally, and there are so many advanced CMS'es that could be used
> and would be "fast enough" (particularly if you put a web cache in front
> of them).
>
> Just my $.01,
>
> -- Leif
>
Re: ASF CMS: Site and Documentation
Posted by Leif Hedstrom <zw...@apache.org>.
On 10/23/2010 09:09 AM, Miles Libbey wrote:
> What problems are we trying to solve by this effort? Do you envision this replacing the cwiki, the documentation (Administrator and SDK Guides), the site (http://trafficserver.apache.org/), or some combination?
My personal view of "importance" here would be
1) Documentation (particularly SDK, but also Admin Guide). It's unwieldy
to manage I think. I think a requirement in a "rewrite" of this is that
it can produce documentations in some easily printable or distributable
format (e.g. as a PDF file).
2) Web site. This pretty much works as is IMO, and unless we get to the
point where we add more content, I see little value in changing the web
site right now. However, I think we need to get better at promoting some
of the "drafts" out of the CWiki, and turn it into real pages on the Web
site. This way, we can use the CWiki as the day to day work space, and
the web site for all the 'released' official statements and documents
(e.g. release plans etc.). This would also make a nicer user experience,
making the Web site the "one stop shop" for all relevant Apache TS
information.
3) CWiki. You'll have to make a really (*really*) hard sell to get rid
of the CWiki. I'm not a huge Confluence fan, but I'm even less of fan
of 'static content' web site / Wikis. It just simply makes no sense to
me personally, and there are so many advanced CMS'es that could be used
and would be "fast enough" (particularly if you put a web cache in front
of them).
Just my $.01,
-- Leif
Re: ASF CMS: Site and Documentation
Posted by Miles Libbey <ml...@apache.org>.
On Oct 23, 2010, at 8:36 AM, Igor Galić wrote:
> Why would it be sensible to replace it?
>
> Because I find it daunting, at best, to do any changes in the
> documentation.
> What I'm hoping to achieve is that anyone can easily contribute fixes
> to the site and the documentation.
Is it daunting because:
- it's html? (there are some decent free and commercial WYSIWYG editors)
- Server side includes are confusing?
- how the files are organized is confusing/don't know where to start? (I just put together http://trafficserver.apache.org/README.html)
- something else?
miles
> I hope that puts my rationale into context.
>
> i
>
>> On Oct 22, 2010, at 6:08 PM, Igor Galić wrote:
>>
>>>
>>> Hi folks,
>>>
>>> In the next two weeks I'll try to migrate trafficserver's
>>> documentation to the ASF CMS.
>>>
>>> http://www.staging.apache.org/dev/cms.html
>>>
>>> For this reason I will create a branch in site:
>>>
>>> /site/branches/ats-cms
>>>
>>> And populate it ``by hand'', rather than trying to
>>> convert an svn copy in place.
>>>
>>> We should soon see how it flies!
>>>
>>> Bye,
>>> i
>>>
>>> --
>>> Igor Galić
>>>
>>> Tel: +43 (0) 664 886 22 883
>>> Mail: i.galic@brainsware.org
>>> URL: http://brainsware.org/
>
> --
> Igor Galić
>
> Tel: +43 (0) 664 886 22 883
> Mail: i.galic@brainsware.org
> URL: http://brainsware.org/
Re: ASF CMS: Site and Documentation
Posted by Igor Galić <i....@brainsware.org>.
----- "Miles Libbey" <mi...@yahoo-inc.com> wrote:
> What problems are we trying to solve by this effort? Do you envision
> this replacing the cwiki, the documentation (Administrator and SDK
> Guides), the site (http://trafficserver.apache.org/), or some
> combination?
> miles
Primarily, it's an experiment. I would like to see if it is possible
to replace any of the above, but I'm targeting the documentation and
the site -- not the Cwiki. This has it's own sense and purpose.
Now, anything is possible, of course. The question is:
Why would it be sensible to replace it?
Because I find it daunting, at best, to do any changes in the
documentation.
What I'm hoping to achieve is that anyone can easily contribute fixes
to the site and the documentation.
I hope that puts my rationale into context.
i
> On Oct 22, 2010, at 6:08 PM, Igor Galić wrote:
>
> >
> > Hi folks,
> >
> > In the next two weeks I'll try to migrate trafficserver's
> > documentation to the ASF CMS.
> >
> > http://www.staging.apache.org/dev/cms.html
> >
> > For this reason I will create a branch in site:
> >
> > /site/branches/ats-cms
> >
> > And populate it ``by hand'', rather than trying to
> > convert an svn copy in place.
> >
> > We should soon see how it flies!
> >
> > Bye,
> > i
> >
> > --
> > Igor Galić
> >
> > Tel: +43 (0) 664 886 22 883
> > Mail: i.galic@brainsware.org
> > URL: http://brainsware.org/
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: ASF CMS: Site and Documentation
Posted by Miles Libbey <mi...@yahoo-inc.com>.
What problems are we trying to solve by this effort? Do you envision this replacing the cwiki, the documentation (Administrator and SDK Guides), the site (http://trafficserver.apache.org/), or some combination?
miles
On Oct 22, 2010, at 6:08 PM, Igor Galić wrote:
>
> Hi folks,
>
> In the next two weeks I'll try to migrate trafficserver's
> documentation to the ASF CMS.
>
> http://www.staging.apache.org/dev/cms.html
>
> For this reason I will create a branch in site:
>
> /site/branches/ats-cms
>
> And populate it ``by hand'', rather than trying to
> convert an svn copy in place.
>
> We should soon see how it flies!
>
> Bye,
> i
>
> --
> Igor Galić
>
> Tel: +43 (0) 664 886 22 883
> Mail: i.galic@brainsware.org
> URL: http://brainsware.org/