On 29. 5. 2014, at 11:18, Yoan Blanc <[email protected]> wrote: > On 28. 05. 14 14:00, Jan Åge Lavik wrote: >> >> On Mon, May 19, 2014 at 4:00 PM, Tibor Simko <[email protected]> wrote: >> >> Ad (3), these could come either built-in with the module sources (in >> reST), or else they may have evolved from earlier RFC, see next point. >> >> Seems like we are moving towards more in-source docs with reST and sphinx. I >> guess more verbose pages could be it's own .rst file under docs/ similar to >> how the few HowTos created on pu are. See >> https://github.com/jirikuncar/invenio/tree/pu/docs/developers > > A reST document in the docs + a pull request for comments and versions > handling is imho the best solution to build PEP/RFC-like documents. > > Github issues are good for: "I've got this problem and doesn't really know > how to solve it, should I do (a) or (b)?" > > And the forum for Stackoverflow-like discussions ~ user support, which > doesn't fit github issues or are too lengthy for IRC/hangout. (so many > channels)
I would like to add my understanding of Yoan’s proposal. Please correct me if I’m wrong. “RFCs in docs” 1) create github issue with RFC 2) after/during discussing the issue create a pull request with new document in docs: `docs/rfc/001-feature-proposal.rst` 3) when new idea comes we can create new pull request with updated document `docs/rfc/001-feature-proposal.rst` 4) finally RFC document can be updated (typo fixes), or replaced by new one if necessary Since the latest documentation is built on http://invenio.readthedocs.org since few days ago, we can rely on "RFCs in docs”. Best regards, -- Jiří Kunčar
signature.asc
Description: Message signed with OpenPGP using GPGMail
