[Xorp-users] Xorp documentation

[Ben Greear]

On 02/27/2011 01:14 AM, Pierre Lepropre wrote:
> Ben,
>
>>
>> It always seems easier (and more fun) to do things from scratch, but often taking
>> the time to do incremental improvements produces more long-term
>> gain.  (You can get a re-write 90% done, at large effort, and
>> run out of time/interest, and the end result is still less
>> useful than the original funky documentation.)
>>
>
> I know: it's easier said than done. The only thing you have to be aware
> of: except the most experienced people in XORP, nobody could be able to
> do incremental changes in the current documentation as *every* piece of
> feature has to be overlooked, the SNMP stuff you just told me is a great
> example of that !

Well, don't overestimate my own knowledge of xorp.  It's a huge project
and there is lots I don't know myself, especially about the more interesting
configuration options for various routing protocols, etc.

>> I'm personally not so interested in poking content into a wiki that I'm
>> not 100% certain can be freely copied (ie, what if your project leaders
>> decide to suddenly restrict access, or just turn off the servers).
>> I would like to add your slide-show to the xorp.ct tree and web site
>> if/when you give permission.  And I'll be happy to link to your page
>> when you are ready.
>
> Ben, we are not a private company but a university. Every piece of work
> we would be doing, in such hypothetical conditions, would be with and
> for the whole community. Shutting down servers isn't exactly our policy
> (actually, you'd be surprised of what still runs out there...).
>
> But if you're afraid of that: why not creating a wiki at CandelaTech or
> at some other place neutral where all your fears could be dismissed and
> your hopes fulfilled ? I'd be more than happy to give you our whole
> current content as a basis to start from.

I did a quick read on 'doku', and it seems it stores it's source
in flat text files.  Maybe we could just periodically copy them to
some directory in xorp.ct and commit them?  That way we have a
backup that is easy for everyone to share.

>> For the existing documentation, it's .tex files and found in
>> xorp.ct/docs/*  I don't particularly know latex or ever tried to learn
>> it, but it is not difficult to make changes to the existing text.
>> You can build the postscript&  pdf files with scons from the docs dir.
>
> LaTeX isn't that hard but can be a little bit touchy at the beginning
> (like XORP ;-) ). The thing is, I don't think it would be really
> appropriate to directly modify these pieces of documentation.
>
> In my mind, the LaTeX documentation should be updated with every major
> release and in the meanwhile, all the suggestions should be brought to
> something more likely to bring people in, as a wiki.

That sounds nice...but unless someone else is posting patches, that
means it's all on me.  It will scale much better if other folks put
some effort towards the latex.  For that matter, it doesn't have to
be an official patch against the latex...just an email posting with
corrected text and I'll figure out how to get it in latex if that's
what it takes.

> The slides you were referring to are not my own creation so I'm gonna
> talk about it with my supervisor, and maybe I could get you the source
> files. I don't think there's gonna be any problem with that.

Thanks.  Your wiki is very nicely done.  I don't necessarily want to host
it, but I would like to have the backup files within my control.  Then,
if your project ever does cease operations, I could simply install doku
and bring the wiki back online.  That's basically what I had to do with xorp
(forked it to xorp.ct and hosted it on my own site), so I'm a bit touchy
about these things :)

Thanks,
Ben


-- 
Ben Greear <greearb at candelatech.com>
Candela Technologies Inc  http://www.candelatech.com