<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<div class="moz-cite-prefix">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<b>Top posting with summary of mails above to enable better
discussion</b><br>
<div class="gmail_extra">
<div>
<div dir="ltr">
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);"><br>
</div>
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);"><b>Premise of original mail:</b></div>
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);">
<ul>
<li>Gluster related documentation was spread across
wiki/website-html/gluster-repo and difficult to find.<br>
</li>
<li>We want a new place for documentation(preferebly one
single place)<br>
</li>
<li>The workflow to contribute should be easy for
non-developers too.(should definitely not involve
cloning repo from gerrit and sending patch)<br>
</li>
</ul>
</div>
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);"><br>
</div>
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);"><b>Unanswered questions/ Concerns raised</b></div>
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);">
<ul>
<li>Developer documentation like struct members and
their uses should be in repo so that developers update
it along with code changes, else there is a good
chance docs go outdated.<br>
</li>
<li>What is the reviewing mechanism for patches against
documentation? </li>
<li>What tool/system gives a good inline commenting
feature and can be used for discussion?</li>
</ul>
</div>
<div style="color: rgb(34, 34, 34); font-family: arial,
sans-serif; font-size: small; font-style: normal;
font-variant: normal; font-weight: normal; letter-spacing:
normal; line-height: normal; orphans: auto; text-align:
start; text-indent: 0px; text-transform: none;
white-space: normal; widows: 1; word-spacing: 0px;
-webkit-text-stroke-width: 0px; background-color: rgb(255,
255, 255);"><br>
<br>
<br class="Apple-interchange-newline">
</div>
</div>
</div>
</div>
On 06/23/2015 04:36 PM, Sankarshan Mukhopadhyay wrote:<br>
</div>
<blockquote
cite="mid:CAJWA-5YdWY8d=GGPBoH0W7HbhWkAUKPyRmNwsJ9wjz1qAEMP+g@mail.gmail.com"
type="cite">
<pre wrap="">On Mon, Jun 22, 2015 at 5:24 PM, Shravan Chandrashekar
<a class="moz-txt-link-rfc2396E" href="mailto:schandra@redhat.com"><schandra@redhat.com></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap="">We would like to finalize on the documentation contribution workflow by 26th June 2015.
As we have not yet received any comments/suggestion, we will confirm the recommend workflow after 26th June.
Kindly provide your suggestion on how we can improve this workflow.
</pre>
</blockquote>
<pre wrap="">
There are a couple of aspects which need to be quickly looked through.
(a) a write-up of somewhat detail providing an overview of the new
workflow; how contributors can participate; reviewing mechanism for
patches against documentation; merge and release paths/cadence
(b) at <a class="moz-txt-link-rfc2396E" href="http://review.gluster.org/#/c/11129/"><http://review.gluster.org/#/c/11129/></a> Niels has a comment
about "about design of structures used in the code" and how he thinks
that it is appropriate if "it stays part of the sources and does not
move out."
He also says "For example, I would like to document some of the memory
layout structures and functions, but this documentation will include
source-code comments and a .txt or .md file with additional details.
Spitting that makes it more difficult to keep in sync."
In this particular example, I'd probably say that it would be better
that such documentation is also part of the docs repo. It lends itself
to re-use as and when required (this particular example seems re-use
friendly).
I'd request that this switch-over to the new workflow and repositories
go ahead with the absolute "documentation" content. Examples/cases
like the above mentioned by Niels can be resolved via discussion and
probably not block the switch.
</pre>
<blockquote type="cite">
<pre wrap="">Currently, mediawiki is read-only. We have ported most of the documents from mediawiki to the new repository [1].
If you find any document which is not ported, feel free to raise this by opening an issue in [2] or if you would
like to port your documents, send a pull request.
[1] <a class="moz-txt-link-freetext" href="https://github.com/gluster/glusterdocs">https://github.com/gluster/glusterdocs</a>
[2] <a class="moz-txt-link-freetext" href="https://github.com/gluster/glusterdocs/issues">https://github.com/gluster/glusterdocs/issues</a>
</pre>
</blockquote>
<pre wrap="">
</pre>
<br>
<br>
</blockquote>
<br>
<br>
<br>
</body>
</html>