Re: Need to update README.

We may be talking about two different types of documentation.

I think we all realize that a community-edited wiki that provides hints and kinks would help everyone involved, and probably lessen the time to initially set up HAProxy for the new user.

There is also the official documentation that Willy creates for us and his commercial customers. That really is authoritative, but -understandably- the official docs suffer when Willy needs to spend time coding, and vice versa.

I think we can readily implement the first type of documentation, the question is can we migrate what Willy is doing to a wiki-type environment.

Anyways, what about making a wiki for user's hints and kinks on setup, and just converting Willy's doc every so often (monthly, quarterly, etc). That way Willy's workflow doesn't get interrupted. Having the official docs be immutable makes the process one-way, so Willy doesn't have to merge changes back in.

Thoughts?

-Dan Zubey

Willy Tarreau wrote:
> On Tue, Apr 29, 2008 at 04:57:20PM -0400, Brian Gupta wrote:
>
>> Since I have to read the docs anyway, I don't mind taking a first pass
>> at wikifying them as I go along. (It will make my life so much easier
>> down the road). What wiki software do you plan to setup? (If you are
>> going to use Twiki, I can start wikifying it now, as I have a private
>> Twiki setup.).
>>
>
> Dan had already set it up and it was not rendered bad at all. He says
> he takes the fault for it not been complete, but he's wrong. It is
> just that the wiki was started too early during a major rework of the
> doc. I couldn't afford to maintain both versions in parallel, and we
> did not talk about how to bring back the changes from the wiki to the
> mainstream doc.
>
> The doc has clearly settled down now. There is still a big chunk about
> logging to move from the old one, and after that we'll be able to remove
> the old and obsolete files.
>
> In the mean time, main questions will concern :
> - process from wiki to mainstream. Maybe simply archive sync points
> then diff ?
>
> - updates from mainstream to wiki. Easier using "git diff -- doc/"
> but still needs a human being to apply the changes.
>
> - provide a fast search interface. When I look for docs on the net,
> I always grab the "all-in-one" versions and never the "one page
> per click", because it's far easier to Ctrl-F anything in a local
> doc, then move around than it is to send search requests in an
> interface and only get a small view in return.
>
> - plan to add more docs (the application guide, then other ones).
>
> Regards,
> Willy
>
>
Received on 2008/05/01 19:40