Missing developer documentation
Hiall, 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
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:
Hiall,
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@lists.frrouting.org https://lists.frrouting.org/listinfo/dev
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@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@lists.frrouting.org <mailto:dev@lists.frrouting.org> https://lists.frrouting.org/listinfo/dev <https://lists.frrouting.org/listinfo/dev>
_______________________________________________ dev mailing list dev@lists.frrouting.org https://lists.frrouting.org/listinfo/dev
Hi Quentin, Lou, I search in my note and didn't find any reference to this decision nor any answer to my original mail on the list. I just remember that we talk about the developer documentation during a weekly meeting, but didn't remember about such decision. Perhaps David has a better memory. Disregarding this point, I agree with Lou about documentation format. We must keep only one. Up to now, we have 4 different formats: txt, texi, md and rest. There is at least 2 too many. I mean, texi is mandatory in order to produce man pages and then we have to choose between txt, md and rest. Txt is too light and don't allow any emphasis. So, the choice is between md and rest. Just to helpin the decision, there is converter between the rest and md format that allowus to not loose previous efforts and contributions: https://github.com/chrissimpkins/md2rst https://github.com/cgwrench/rst2md Regards Olivier Le 11/12/2017 à 22:34, Quentin Young a écrit :
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
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
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@labn.net <mailto:lberger@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:
Hiall,
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@lists.frrouting.org https://lists.frrouting.org/listinfo/dev
_______________________________________________ dev mailing list dev@lists.frrouting.org <mailto:dev@lists.frrouting.org> https://lists.frrouting.org/listinfo/dev
_______________________________________________ dev mailing list dev@lists.frrouting.org https://lists.frrouting.org/listinfo/dev
_________________________________________________________________________________________________________________________ Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration, Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci. This message and its attachments may contain confidential or privileged information that may be protected by law; they should not be distributed, used or copied without authorisation. If you have received this email in error, please notify the sender and delete this message and its attachments. As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified. Thank you.
Thanks Olivier, see below. On 12/12/2017 07:55 AM, olivier.dugeon@orange.com wrote:
Hi Quentin, Lou,
I search in my note and didn't find any reference to this decision nor any answer to my original mail on the list. I just remember that we talk about the developer documentation during a weekly meeting, but didn't remember about such decision. Perhaps David has a better memory.
Disregarding this point, I agree with Lou about documentation format. We must keep only one. Up to now, we have 4 different formats: txt, texi, md and rest. There is at least 2 too many. I mean, texi is mandatory in order to produce man pages and then we have to choose between txt, md and rest. Txt is too light and don't allow any emphasis. So, the choice is between md and rest.
I'm okay with either, but have a slight bias for not changing unless there is a good reason to change. Quoting from the compatibility section of Community.md, which I think is generally applicable here: This is not to say that minor or even major functional changes to CLI and common code should be avoided, but rather that the benefit gained from a change should be weighed against the added cost/complexity to existing code. Most important to me is for there to be a community discussion and agreement. If we have closed/limited discussion on direction changes of the project, we'll be no better off than we were before the fork. For me this is the most important attribute of FRR, i.e., that it is community driven vs driven by the decisions of one (person, company, interest group, etc). If we revert to that model of operation, my interest in this project will severely wane. Thanks, Lou
Just to helpin the decision, there is converter between the rest and md format that allowus to not loose previous efforts and contributions:
https://github.com/chrissimpkins/md2rst
https://github.com/cgwrench/rst2md
Regards
Olivier
Le 11/12/2017 à 22:34, Quentin Young a écrit :
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
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
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@labn.net <mailto:lberger@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:
Hiall,
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@lists.frrouting.org https://lists.frrouting.org/listinfo/dev
_______________________________________________ dev mailing list dev@lists.frrouting.org <mailto:dev@lists.frrouting.org> https://lists.frrouting.org/listinfo/dev
_______________________________________________ dev mailing list dev@lists.frrouting.org https://lists.frrouting.org/listinfo/dev
_________________________________________________________________________________________________________________________
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration, Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.
This message and its attachments may contain confidential or privileged information that may be protected by law; they should not be distributed, used or copied without authorisation. If you have received this email in error, please notify the sender and delete this message and its attachments. As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified. Thank you.
Hi Lou, Le 12/12/2017 à 14:17, Lou Berger a écrit : [...]
Most important to me is for there to be a community discussion and agreement.
If we have closed/limited discussion on direction changes of the project, we'll be no better off than we were before the fork. For me this is the most important attribute of FRR, i.e., that it is community driven vs driven by the decisions of one (person, company, interest group, etc). If we revert to that model of operation, my interest in this project will severely wane. Completely agree with you. Now, the main problem is more on process. We have not setup rules for the weekly meeting to produce meeting minutes which must be review during the next meeting or on the mailing list. If such principle has been in place, we could look to the archive and fix this issue immediately instead of trying to remember what have been said during a summer meeting ...
[...] Regards Olivier
Hi Olivier, On 12/12/2017 8:52 AM, Olivier Dugeon wrote:
Hi Lou,
Le 12/12/2017 à 14:17, Lou Berger a écrit :
[...]
Most important to me is for there to be a community discussion and agreement.
If we have closed/limited discussion on direction changes of the project, we'll be no better off than we were before the fork. For me this is the most important attribute of FRR, i.e., that it is community driven vs driven by the decisions of one (person, company, interest group, etc). If we revert to that model of operation, my interest in this project will severely wane. Completely agree with you. Now, the main problem is more on process. We have not setup rules for the weekly meeting to produce meeting minutes which must be review during the next meeting or on the mailing list. If such principle has been in place, we could look to the archive and fix this issue immediately instead of trying to remember what have been said during a summer meeting ... I just sent a PR to document what I have understood to be our process, but you're right it wasn't documented and should have been...
The Development list is used to discuss and document general issues related to project development and governance. The public Slack instance, frrouting.slack.com, and weekly technical meetings provide a higher bandwidth channel for discussions. The results of such discussions must be reflected in updates, as appropriate, to code (i.e., merges), [github](https://github.com/FRRouting/frr/issues) tracked issues, and for governance or process changes, updates to the Development list and either this file or information posted at [https://frrouting.org/](https://frrouting.org/).
[...]
Regards
Olivier
participants (4)
-
Lou Berger -
Olivier Dugeon -
olivier.dugeon＠orange.com
-
Quentin Young