[Gluster-devel] [Gluster-users] Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An Update)

Niels de Vos ndevos at redhat.com
Fri Jul 24 09:06:34 UTC 2015 

On Fri, Jul 24, 2015 at 10:43:47AM +0530, Humble Devassy Chirammal wrote:
> >>
> This is still confising me a little. The presentations from the
> Mediawiki instance have been put in the <glusterdocs>/presentations/
> directory. If we should put them on the website instead, they should not
> be part of glusterdocs. However, there is currently no page that I can
> find on the website that lists the different presentations. The only
> link that I can find is this one:
> 
>   http://gluster.readthedocs.org/en/latest/presentations/
> 
> Is that going to be replaced with an explanation (or pointer) on how to
> get the presentation on the website?
> >>
> 
> 
> Well, we are yet to finalize on it.  If we can render it on website we will
> do the same. Otherwise it will be a pointer from website.

Do you have a list of pending tasks that need to be completed before we
can say that the migration is done? Things that I would expect to see in
that list include at least:

- add a README.md to the glusterdocs project with (or pointing to) the
  complete documentation workflow
- populate the glusterfs-specs repository with existing design docs (are
  these the ones from the wiki?)
- get the glusterfs-specs repo from GitHub in Gerrit, GitHub should only
  be a read-only mirror
- publish glusterfs-specs on readthedocs (or somewhere else)
- get the presentations (linked) on the website
- redirect the converted wiki pages to glusterdocs/glusterfs-specs

I'm pretty sure that there are other tasks, these are just the first
that I could think of. It would help to be able to track progress and
have a rough estimate on when each task is expected to be finished.
Maybe file bugs in Bugzilla, or issues in GitHub? I'm not sure what the
plan is to track requests for the documentation, that should be written
down somewhere too.

Thanks,
Niels


> 
> 
> --Humble
> 
> 
> On Fri, Jul 24, 2015 at 2:00 AM, Niels de Vos <ndevos at redhat.com> wrote:
> 
> > On Wed, Jul 22, 2015 at 03:51:59PM +0530, Anjana Sriram wrote:
> > > Hello All,
> > >
> > > Thank you for the feedback and suggestions provided on the GlusterFS
> > > Documentation improvements. We have analyzed them and here's a proposal
> > to
> > > address them:
> > >
> > > We plan to use three independent repos for our projects:
> > >
> > ... snip
> > >
> > > /Static Documentation/: Currently, Mediawiki is read-only. We have ported
> > > most of the documents from Mediawiki. There few pages which do not
> > qualify
> > > to be placed in the above three repos for example, Presentations  which
> > will
> > > be considered to be placed on the website.
> >
> > This is still confising me a little. The presentations from the
> > Mediawiki instance have been put in the <glusterdocs>/presentations/
> > directory. If we should put them on the website instead, they should not
> > be part of glusterdocs. However, there is currently no page that I can
> > find on the website that lists the different presentations. The only
> > link that I can find is this one:
> >
> >   http://gluster.readthedocs.org/en/latest/presentations/
> >
> > Is that going to be replaced with an explanation (or pointer) on how to
> > get the presentation on the website?
> >
> > Thanks,
> > Niels
> >
> >
> > >
> > > Your thoughts and feedback are the major influences to our constant
> > endeavor
> > > to make the community documentation better, effective, and useful. Please
> > > revert with your thoughts and feedback on the above proposal outlined by
> > > 29th July 2015.
> > >
> > > Regards,
> > > Humble, Shravan, and Anjana
> > >
> > > On 06/22/2015 05:24 PM, Shravan Chandrashekar wrote:
> > > >Hello all,
> > > >
> > > >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.
> > > >
> > > >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] https://github.com/gluster/glusterdocs
> > > >[2] https://github.com/gluster/glusterdocs/issues
> > > >
> > > >Regards,
> > > >Shravan
> > > >
> > > >----- Original Message -----
> > > >From: "Humble Devassy Chirammal" <humble.devassy at gmail.com>
> > > >To: "Gluster-users at gluster.org List" <gluster-users at gluster.org>,
> > "Gluster Devel" <gluster-devel at gluster.org>
> > > >Sent: Wednesday, May 27, 2015 7:48:16 PM
> > > >Subject: [Gluster-devel] GlusterFS Documentation Improvements - An
> > Update
> > > >
> > > >
> > > >Hello all,
> > > >
> > > >The GlusterFS documentation team is constantly working to improve the
> > quality, findability, and usefulness of its documentation. Our goal is to
> > increase community contribution, remove barriers that discourage
> > contribution and give you the help you need, when and where you need it. As
> > part of this strategy, we’ve just rolled out the revamped GlusterFS
> > Documentation: gluster.readthedocs.org
> > > >
> > > >We started by curating content from various sources including
> > gluster.org static HTML documentation, various blog posts and the
> > Community wiki. We used readthedocs service to host the documentation and
> > mkdocs to convert the Markdown source files to HTML pages. We also put our
> > thought into classifying the documentation based on their content:
> > > >
> > > >
> > > >
> > > >     * Quick Start Guide : A headstart guide for the beginners.
> > > >
> > > >
> > > >     * Installation Guide : Step by step instructions to install
> > GlusterFS.
> > > >
> > > >
> > > >     * Administration Guide : Container for for all administrative
> > actions.
> > > >
> > > >
> > > >     * Developer Guide : Container for all development related aspects.
> > > >
> > > >
> > > >     * Upgrade Guide : Contains guides to upgrade from older versions
> > of GlusterFS.
> > > >
> > > >
> > > >     * Features : Container for all the features of GlusterFS
> > introduced in various versions.
> > > >
> > > >
> > > >     * GlusterFS Tools : Contains information about the tools used in
> > GlusterFS.
> > > >
> > > >
> > > >     * Troubleshooting Guide : Container for basic troubleshooting and
> > debugging guides.
> > > >
> > > >
> > > >     * Images : Container for images (in .jpg or .png format) that are
> > present inline the documentation pages.
> > > >
> > > >Doing so, we gain these benefits:
> > > >
> > > >
> > > >
> > > >     * Version based browsable documentation
> > > >
> > > >
> > > >     * More targeted content
> > > >
> > > >
> > > >     * Less duplication
> > > >
> > > >
> > > >     * Faster updates
> > > >
> > > >Whats changing for community members?
> > > >
> > > >A very simplified contribution workflow.
> > > >
> > > >- How to Contribute?
> > > >
> > > >Contributing to the documentation requires a github account. To edit on
> > github, fork the repository (see top-right of the screen, under your
> > username). You will then be able to make changes easily. Once done, you can
> > create a pull request and get the changes reviewed and merged into the
> > official repository.
> > > >With this simplified workflow, the documentation is no longer
> > maintained in gluster/glusterfs/docs directory but it has a new elevated
> > status in the form of a new project: gluster/glusterdocs (
> > https://github.com/gluster/glusterdocs) and currently this project is
> > being maintained by Anjana Sriram, Shravan and Humble.
> > > >
> > > >- What to Contribute
> > > >
> > > >Really, anything that you think has value to the GlusterFS developer
> > community. While reading the docs you might find something incorrect or
> > outdated. Fix it! Or maybe you have an idea for a tutorial, or for a topic
> > that isn’t covered to your satisfaction. Create a new page and write it up!
> > > >
> > > >Whats Next?
> > > >
> > > >Since the GlusterFS documentation has a new face-lift, MediaWiki will
> > no longer be editable but will only be READ ONLY view mode. Hence, all the
> > work-in-progress design notes which were maintained on MediaWiki will be
> > ported to the GitHub repository and placed in "Feature Plans" folder. So,
> > when you want to upload your work in progess documents you must do a pull
> > request after the changes are made. This outlines the change in workflow as
> > compared to MediaWiki.
> > > >
> > > >A proposal:
> > > >
> > > >Another way to maintain work-in-progress documents in Google docs (o r
> > any other colloborative editing tool) and link them as an index entry in
> > Feature Plans page on GitHub. This can be an excellent way to track a
> > document through multiple rounds of collaborative editing in real time.
> > > >
> > > >
> > > >
> > > >Stay tuned for a more detailed information about the new contribution
> > workflow, which will be posted on the new documentation website (i.e.
> > gluster.readthedocs.org )
> > > >
> > > >We love to hear your feedback on this. Any suggestions/comments
> > regarding this would help !
> > > >
> > > >--Humble
> > > >
> > > >
> > > >_______________________________________________
> > > >Gluster-devel mailing list
> > > >Gluster-devel at gluster.org
> > > >http://www.gluster.org/mailman/listinfo/gluster-devel
> > >
> >
> > > _______________________________________________
> > > Gluster-users mailing list
> > > Gluster-users at gluster.org
> > > http://www.gluster.org/mailman/listinfo/gluster-users
> >
> > _______________________________________________
> > Gluster-users mailing list
> > Gluster-users at gluster.org
> > http://www.gluster.org/mailman/listinfo/gluster-users

More information about the Gluster-devel mailing list