Re: [docs][RFC] GitBook documentation process

["Kinney, Michael D" <michael.d.kinney@intel.com>]

Hi Leif,

Thanks for the feedback.  I will update the RFC.

I only used my personal GitHub and GitBook accounts as a 
staging area for the RFC discussion/approval.

I will migrate all GitHub and GitBook content to Tianocore
accounts once approved.  The official GitBook account for
publishing will be named Tianocore-Docs.

The Tianocore website documents areas will also be updated 
with links to published docs from the Tianocore-docs GitBook
account.

Mike

> -----Original Message-----
> From: Leif Lindholm [mailto:leif.lindholm@linaro.org]
> Sent: Monday, March 20, 2017 11:19 AM
> To: Kinney, Michael D <michael.d.kinney@intel.com>
> Cc: edk2-devel@lists.01.org
> Subject: Re: [edk2] [docs][RFC] GitBook documentation process
> 
> Hi Mike,
> 
> I agree with Laszlo's comments (including that this looks really
> good!). Just one question below:
> 
> On Fri, Mar 17, 2017 at 01:07:59AM +0000, Kinney, Michael D wrote:
> > Hello,
> >
> > The following is an RFC proposal for using GitBook for tianocore
> > documentation.  This RFC is also available at the following link:
> >
> > * https://github.com/mdkinney/edk2-TemplateSpecification/wiki
> >
> > Please review this proposal and the referenced documents and
> > provide any comments or concerns you may have.
> >
> > The Sample GitBook documents are hosted in personal GitHub and
> > personal GitBook pages.  When this RFC is approved, these will
> > documents be migrated to Tianocore pages and additional EDK II
> > related documents will be added as the conversion to GitBook
> > format is completed.
> >
> > Please provide feedback by 3/24/2017.
> >
> > Thanks,
> >
> > Mike
> >
> > =======================================================================
> >
> > # Introduction
> >
> > This RFC provide a proposal to create and maintain open source documents
> > associated with the Tianocore project.  Markdown is a document source format
> > that is compatible with the patch review process that is currently used for
> > EDK II source changes.  [GitBook](https://www.gitbook.com) is a document
> > publishing service that uses Markdown as an input format and can generate
> > published documents as web pages, PDF, MOBI, and EPUB and provide a GitHub
> > integration service that supports pulling Markdown sources from GitHub hosted
> > repositories.
> >
> > There are several elements to this proposal:
> >
> > * Update of the TianoCore Contribution Agreement from Version 1.0 to
> >   Version 1.1 to cover open source documentation associated with the
> >   TianoCore project.  The following is a link to the revised agreement.
> >
> >   https://github.com/mdkinney/edk2-
> TemplateSpecification/blob/master/CONTRIBUTIONS.txt
> >
> > * New license for TianoCore documentation source files and TianoCore published
> >   documents.  The following is a link to the license that is based on the
> >   [FreeBSD Documentation License](https://www.freebsd.org/copyright/freebsd-doc-
> license.html):
> >
> >   https://github.com/mdkinney/edk2-TemplateSpecification/blob/master/LICENSE.txt
> >
> > * Use [TianoCore-Docs](https://github.com/tianocore-docs) GitHub organization to
> >   host the GIT repositories for TianoCore documents.  The reason a new organization
> >   is being used is because the GitBook services requires one GIT repository per
> >   document.  A separate organization separates the source code repositories from
> >   documentation repositories.
> >
> > * Use [TianoCore Bugzilla](https://bugzilla.tianocore.org) to report document issues
> >
> > * Use the same patch review process that is used for EDK II source code to provide
> >   changes to TianoCore documents with the differences listed below.  This is a very
> >   brief summary.  A second RFC and/or Wiki page will cover the detailed process.
> >
> >   1. Use `[docs]` tag in email discussions.
> >
> >       `[edk2][docs] Subject`
> >
> >   2. Use `[docs][repo-name PATCH]` tag in patch review emails.
> >
> >       `[edk2][docs][edk2-DecSpecification PATCH] Fix typo in Section 2.7`
> >
> >   3. Use TianoCore Contribution Agreement 1.1 in commit message
> >
> >       `Contributed-under: TianoCore Contribution Agreement 1.0`
> >
> >   4. Send email to edk2-devel to request creation of new document repository
> >      and link the repository to the GitBook publishing services.
> >
> >       `[edk2][docs][edk2-NewSpecification] Create repository for New Specification`
> >
> >   5. Send email to edk2-devel to announce the creation of document release branch.
> >
> >       `[edk2][docs][edk2-DecSpecification] Create release/0.30 branch`
> >
> >   6. The `master` branch of a document repository is always the latest DRAFT version
> >      of the document.
> >
> >   7. Released versions of documents are always on a release branch with a naming
> >      convention of `release/x.yy`.
> >
> > # Sample EDK II Documents in GitBook Format
> >
> > A couple of documents have been used to prototype this proposal.  A new document
> > called _EDK II Template Specification_ has been created to provide a sample that
> > can be used to start new documents.  It can also be updated over time to provide
> > examples of the Markdown syntax required for specific document styles and experiment
> > with refinements to the document management process.  The second document is the
> > _EDK II Package Declaration (DEC) File Format Specification_ that has been converted
> > to GitBook.  This GitBook version can be compared against current version at:
> > https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC_Spec_1_25.pdf
> >
> > Here are the links to the _EDK II Template Specification_ in a personal GitHub
> > repository and linked to a personal GitBook account.  The DRAFT version of the
> > _EDK II Template Specification_ is in the `master` branch, and the released version
> > is in the `releases/0.10` branch.  This template also shows some example usage of
> > the [PlatUML](http://plantuml.com) to implement figures and diagrams.
> >
> > * https://github.com/mdkinney/edk2-TemplateSpecification
> > * https://www.gitbook.com/book/mdkinney/edk-ii-template-specification
> >
> > Here are the links to the GitBook published documents
> >
> > * _EDK II Template Specification_ DRAFT
> >   + WEB: https://www.gitbook.com/read/book/mdkinney/edk-ii-template-specification
> >   + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-template-
> specification
> >   + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-template-
> specification
> >   + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-template-
> specification
> > * _EDK II Template Specification_ Revision 0.10
> >   + WEB: https://mdkinney.gitbooks.io/edk-ii-template-
> specification/content/v/release/0.1/
> >   + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-template-
> specification/v/release/0.1
> >   + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-template-
> specification/v/release/0.1
> >   + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-template-
> specification/v/release/0.1
> >
> > Here are the links to the _EDK II Package Declaration (DEC) File Format
> Specification_
> > in a personal GitHub repository and linked to a personal GitBook account.  The DRAFT
> > version of this specification is in the `master` branch.
> >
> > * https://github.com/mdkinney/edk2-DecSpecification
> > * https://www.gitbook.com/book/mdkinney/edk-ii-dec-specification
> >
> > * _EDK II Package Declaration (DEC) File Format Specification__ DRAFT
> >   + WEB: https://www.gitbook.com/read/book/mdkinney/edk-ii-dec-specification
> >   + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-dec-specification
> >   + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-dec-
> specification
> >   + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-dec-
> specification
> >
> 
> These pre-rendered versions look great, but should we have have some
> official gitbook account to link against rather than your personal
> one? Or do we have an alternative plan for publication?
> 
> Regards,
> 
> Leif
> 
> > # Resources
> >
> > * [GitHub TianoCore](https://github.com/tianocore)
> > * [GitHub TianoCore-Docs](https://github.com/tianocore-docs)
> > * [TianoCore Bugzilla](https://bugzilla.tianocore.org)
> > * [GitBook](https://www.gitbook.com)
> > * [GitBook ToolChain Documentation](https://toolchain.gitbook.com/)
> > * [GitBook MarkDown](https://toolchain.gitbook.com/syntax/markdown.html)
> > * [GitBook Editor](https://www.gitbook.com/editor)
> > * [PlantUML](http://plantuml.com)
> > * [PlantUML Language Specification](http://plantuml.com/sitemap-language-
> specification)
> >
> > =======================================================================
> > _______________________________________________
> > edk2-devel mailing list
> > edk2-devel@lists.01.org
> > https://lists.01.org/mailman/listinfo/edk2-devel