httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nóirín Plunkett <noi...@apache.org>
Subject Re: Proposal to move docs to Apache CMS
Date Wed, 02 May 2012 21:50:21 GMT
On Wed, May 2, 2012 at 2:40 PM, André Malo <nd@perlig.de> wrote:
> * Nóirín Plunkett wrote:
>>
>> I, for one, welcome our new CMS overlords :-)
>>
>> Seriously though, the hassle of checking out the docs tree, finding
>> the build tree, remembering where I'm meant to check that out to, ...
>> is, well, a hassle.
>
> Well. There's not effort needed for *that* hassle. It's documented on the
> docs-project pages (since ever). [1] [2]
>
> http://httpd.apache.org/docs-project/docsformat.html

Except that that page is a nightmare to find, and only tells me what
to do after I'm already on step three.

It might not seem like much hassle to you, but it's enough to blow
away my motivation to fix anything.

> OTOH, remembering where the CMS is and how it works, would actually be a
> hassle for *me* (and I'd guess, various developers trying to write
> documentation while writing code, too [which should be encouraged!]).

For me, "the CMS" is just a bookmarklet in my browser. And when I'm on
a new machine, or I've forgotten how it works, I search for apache cms
and a set of reasonably clear instructions pops up as the third result
in Google.

> - Also it's a nice thing to check in documentation together with code. From
>  time to time patches arrive that way. In fact, I'd rather support more of
>  those.

Agreed.

> - Oh, patches. How does the CMS deal with those in general? Do I need to
>  apply them manually then in a browser window?
>
> - Which leads to the next point: I've never used the CMS. How does it play
>  together with my own editor?
>
> - How does the CMS play along with the other build targets (CHM, tarball). I
>  guess, it does not at all (CHM needs windows in very specific
>  configurations). So we still need a separate build system then?
>
> - How does the CMS handle the build output? (e.g. ./build.sh de emits the
>  outdated de-translations at the end)

I don't know the answers to these questions, and I certainly don't
assume that the CMS is perfect. Moving to the CMS will almost
certainly require changes in workflow, and may well make things harder
for some people. But our current system effectively excludes other
people. That may be ok with y'all, in which case I'll go back to
lurking, but I'd rather be knowingly excluded than silently :-)

> [1] *Sigh* I'm wondering, why so many people here don't know about OUR
>    docs-project pages.

They're hard to find. Even when I know they exist, I can't find them.

> [2] Not everybody needs to run the build system (some people don't even have
>    java on their box). Someone else will run it then at the next
>    opportunity. In fact, it's encouraged that you run it only on languages
>    you understand enough.

I've broken the build with poor XML more than once, so I don't like to
check in anything I haven't built.

N

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message