[dev] Missing developer documentation

[Quentin Young]

Just to add some background here—

My recollection is that we held the meeting Lou mentioned between the date of Olivier’s email (July 25) and August 8th. On August 8th, we merged the following pull request from David Lamparter:

https://github.com/FRRouting/frr/pull/929 <https://github.com/FRRouting/frr/pull/929>

Note my comment on this PR (#929) where I state my opinion on the need to make a decision on the docs format before merging RST. The comment was later edited (with the edited part marked) to state we had agreed on RST; as I recall, I did this because we agreed on RST in a meeting.

The current PR Lou referenced is this one:

https://github.com/FRRouting/frr/pull/1530 <https://github.com/FRRouting/frr/pull/1530>

In light of #929, referring to #1530 as “starting this change” may be a slight mischaracterization. My 2c.

Quentin

> On Dec 11, 2017, at 4:18 PM, Lou Berger <lberger at labn.net> wrote:
> 
> so it seems there was some discussion on this in August where the agreement among those who participated in that weekly call was to move to reStructuredText (reST) .
> 
> Does anyone care to comment on this? , i.e. are you (not) okay with replacing the current md and texi formats with reST?  
> There is a PR starting this change...
> 
> Thanks,
> 
> Lou
> PS  I have no memory of the discussion (and may even have been there with glazed over eyes) so was surprised by the PR
> 
> On 7/25/2017 9:35 AM, Olivier Dugeon wrote:
>> Hi all,
>> 
>> There is missing developer documentation in FRR. In PR #805 I try to update an old Zebra hacking document, but that seems too old to be publish, so I prefer to remove it as suggested during the PR review.
>> 
>> For me, the main problem is how to start writing a such documentation ?
>> 
>> First, it is too huge and to complicated to be written by only one person.
>> 
>> Second, we need a dedicated space (e.g. a new doc project inside FRRouting) to collectively write such documentation and then push into frr master documents when they are ready.
>> 
>> Finally, we need to organize themselves in order to collectively decided how to write them, to formalize the document through a common template, to harmonize the documentation ...
>> 
>> I would start by proposing:
>>   * start discussion about this new topic (create a new issue in github) during regular meeting
>>   * decide the document format (Markdown, in line github Wiki, LaTeX, TeXi ...)
>>   * create a new doc project within FRRouting
>>   * propose template
>>   * propose Table of Content for each document (perhaps partially common)
>>   * open contribution to the different documents
>> 
>> Comments are welcome.
>> 
>> 
>> Regards
>> 
>> Olivier
>> 
>> 
>> 
>> _______________________________________________
>> dev mailing list
>> dev at lists.frrouting.org <mailto:dev at lists.frrouting.org>
>> https://lists.frrouting.org/listinfo/dev <https://lists.frrouting.org/listinfo/dev>
> 
> _______________________________________________
> dev mailing list
> dev at lists.frrouting.org
> https://lists.frrouting.org/listinfo/dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frrouting.org/pipermail/dev/attachments/20171211/dbc8233f/attachment.html>