The katello project has sorely lacked good user documentation in the
past and I've started work on remedying some of that. Instead of going
the normal wiki route, I thought about trying simple markdown files in git:
(The content views documentation is still more or less a WIP)
I wanted to get people's thoughts before I continued working or opened
up a pull request. After working through 1 1/2 pages, it seems much
much easier than working with the trac-based fedora wiki. A few of the
benefits:
Much easier uploading of images (especially multiple images)
Easier syntax IMHO
Built in versioning
When editing within github itself, you can preview without a page
reload. A simple thing, but very nice.
Doc changes can be included with code pull requests. ("Hey, did you
forget to update the docs??")
I would be for migrating wiki completely to git and MD files.
···
On 14.10.13 5:40, Justin Sherrill wrote:
>
> The katello project has sorely lacked good user documentation in the
> past and I've started work on remedying some of that. Instead of going
> the normal wiki route, I thought about trying simple markdown files in git:
>
> https://github.com/jlsherrill/katello/blob/docs/doc/guides/content.md
> https://github.com/jlsherrill/katello/blob/docs/doc/guides/content_views.md
>
> (The content views documentation is still more or less a WIP)
>
> I wanted to get people's thoughts before I continued working or opened
> up a pull request. After working through 1 1/2 pages, it seems much
> much easier than working with the trac-based fedora wiki. A few of the
> benefits:
>
> * Much easier uploading of images (especially multiple images)
> * Easier syntax IMHO
> * Built in versioning
> * When editing within github itself, you can preview without a page
> reload. A simple thing, but very nice.
> * Doc changes can be included with code pull requests. ("Hey, did you
> forget to update the docs??")
> * Doc updates/additions go through a review
>
> Thoughts?
>
> -Justin
>
> _______________________________________________
> katello-devel mailing list
> katello-devel@redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel
···
----- Original Message -----
> I like working with the Github files much better than Trac. However, my
> concern would be the use of it for user docs. I think user docs have a
> different audience than dev docs--an audience that might not know how to use
> git or Github.
>
> I wonder though if there's maybe some way we could put the user docs into a
> specific folder and then somehow automatically publish them to a web
> address. I think that would solve the problem.
>
> David
>
> ----- Original Message -----
> > From: "Petr Chalupa"
> > To: "Justin Sherrill"
> > Cc: "foreman-dev" , katello-devel@redhat.com
> > Sent: Monday, October 14, 2013 2:32:11 AM
> > Subject: Re: [katello-devel] [Katello] Git-based katello user docs
> >
> > I totally agree +100 :)
> >
> > I would be for migrating wiki completely to git and MD files.
> >
> > On 14.10.13 5:40, Justin Sherrill wrote:
> > >
> > > The katello project has sorely lacked good user documentation in the
> > > past and I've started work on remedying some of that. Instead of going
> > > the normal wiki route, I thought about trying simple markdown files in
> > > git:
> > >
> > > https://github.com/jlsherrill/katello/blob/docs/doc/guides/content.md
> > > https://github.com/jlsherrill/katello/blob/docs/doc/guides/content_views.md
> > >
> > > (The content views documentation is still more or less a WIP)
> > >
> > > I wanted to get people's thoughts before I continued working or opened
> > > up a pull request. After working through 1 1/2 pages, it seems much
> > > much easier than working with the trac-based fedora wiki. A few of the
> > > benefits:
> > >
> > > * Much easier uploading of images (especially multiple images)
> > > * Easier syntax IMHO
> > > * Built in versioning
> > > * When editing within github itself, you can preview without a page
> > > reload. A simple thing, but very nice.
> > > * Doc changes can be included with code pull requests. ("Hey, did you
> > > forget to update the docs??")
> > > * Doc updates/additions go through a review
> > >
> > > Thoughts?
> > >
> > > -Justin
> > >
> > > _______________________________________________
> > > katello-devel mailing list
> > > katello-devel@redhat.com
> > > https://www.redhat.com/mailman/listinfo/katello-devel
> >
> > _______________________________________________
> > katello-devel mailing list
> > katello-devel@redhat.com
> > https://www.redhat.com/mailman/listinfo/katello-devel
> >
>
> _______________________________________________
> katello-devel mailing list
> katello-devel@redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel
>
···
On Mon, Oct 14, 2013 at 9:32 AM, Petr Chalupa wrote:
On 14.10.13 5:40, Justin Sherrill wrote:
The katello project has sorely lacked good user documentation in the
past and I’ve started work on remedying some of that. Instead of going
the normal wiki route, I thought about trying simple markdown files in
git:
(The content views documentation is still more or less a WIP)
I wanted to get people’s thoughts before I continued working or opened
up a pull request. After working through 1 1/2 pages, it seems much
much easier than working with the trac-based fedora wiki. A few of the
benefits:
Much easier uploading of images (especially multiple images)
Easier syntax IMHO
Built in versioning
When editing within github itself, you can preview without a page
reload. A simple thing, but very nice.
Doc changes can be included with code pull requests. (“Hey, did you
forget to update the docs??”)
> I like working with the Github files much better than Trac. However, my concern would be the use of it for user docs. I think user docs have a different audience than dev docs–an audience that might not know how to use git or Github.
>
> I wonder though if there's maybe some way we could put the user docs into a specific folder and then somehow automatically publish them to a web address. I think that would solve the problem.
I would be for migrating wiki completely to git and MD files.
On 14.10.13 5:40, Justin Sherrill wrote:
The katello project has sorely lacked good user documentation in the
past and I’ve started work on remedying some of that. Instead of going
the normal wiki route, I thought about trying simple markdown files in git:
(The content views documentation is still more or less a WIP)
I wanted to get people’s thoughts before I continued working or opened
up a pull request. After working through 1 1/2 pages, it seems much
much easier than working with the trac-based fedora wiki. A few of the
benefits:
Much easier uploading of images (especially multiple images)
Easier syntax IMHO
Built in versioning
When editing within github itself, you can preview without a page
reload. A simple thing, but very nice.
Doc changes can be included with code pull requests. (“Hey, did you
forget to update the docs??”)
>
>
>
>> I like working with the Github files much better than Trac. However, my
>> concern would be the use of it for user docs. I think user docs have a
>> different audience than dev docs–an audience that might not know how to
>> use git or Github.
>>
>> I wonder though if there's maybe some way we could put the user docs into
>> a specific folder and then somehow automatically publish them to a web
>> address. I think that would solve the problem.
>>
>
> +1 I assumed automated publishing.
>
our theforeman.org has auto publish once committed it pushes it to the
website and update it automatically.
Ohad
···
On Mon, Oct 14, 2013 at 2:47 PM, Petr Chalupa wrote:
> On 14.10.13 11:56, David Davis wrote:
(The content views documentation is still more or less a WIP)
I wanted to get people’s thoughts before I continued working or opened
up a pull request. After working through 1 1/2 pages, it seems much
much easier than working with the trac-based fedora wiki. A few of
the
benefits:
Much easier uploading of images (especially multiple images)
Easier syntax IMHO
Built in versioning
When editing within github itself, you can preview without a page
reload. A simple thing, but very nice.
Doc changes can be included with code pull requests. (“Hey, did you
forget to update the docs??”)
>
>
>
>
>
>
>
> I like working with the Github files much better than Trac.
> However, my concern would be the use of it for user docs. I
> think user docs have a different audience than dev docs–an
> audience that might not know how to use git or Github.
>
> I wonder though if there's maybe some way we could put the
> user docs into a specific folder and then somehow
> automatically publish them to a web address. I think that
> would solve the problem.
>
>
> +1 I assumed automated publishing.
>
>
> our theforeman.org <http://theforeman.org> has auto publish once
> committed it pushes it to the website and update it automatically.
+1, I don't want to just stick them in git and point our users to
github, but wasn't really concerned with the publishing aspects of it
atm. I was more trying to gauge interest in github based docs and it
seems like its overwhelmingly favoured. I will continue on down my path
of working on user guides in my spare time. I'm mainly focusing on
things that will not be changing after the engification (other than
possible navigation changes).
-Jusitn
···
On 10/14/2013 07:53 AM, Ohad Levy wrote:
> On Mon, Oct 14, 2013 at 2:47 PM, Petr Chalupa > wrote:
> On 14.10.13 11:56, David Davis wrote:
Ohad
David
----- Original Message -----
> From: "Petr Chalupa" <pchalupa@redhat.com
<mailto:pchalupa@redhat.com>>
> To: "Justin Sherrill" <jsherril@redhat.com
<mailto:jsherril@redhat.com>>
> Cc: "foreman-dev" <foreman-dev@googlegroups.com
<mailto:foreman-dev@googlegroups.com>>,
katello-devel@redhat.com <mailto:katello-devel@redhat.com>
> Sent: Monday, October 14, 2013 2:32:11 AM
> Subject: Re: [katello-devel] [Katello] Git-based katello
user docs
>
> I totally agree +100 :)
>
> I would be for migrating wiki completely to git and MD files.
>
> On 14.10.13 5:40, Justin Sherrill wrote:
> >
> > The katello project has sorely lacked good user
documentation in the
> > past and I've started work on remedying some of that.
Instead of going
> > the normal wiki route, I thought about trying simple
markdown files in git:
> >
> >
https://github.com/jlsherrill/katello/blob/docs/doc/guides/content.md
> >
https://github.com/jlsherrill/katello/blob/docs/doc/guides/content_views.md
> >
> > (The content views documentation is still more or less a WIP)
> >
> > I wanted to get people's thoughts before I continued
working or opened
> > up a pull request. After working through 1 1/2 pages, it
seems much
> > much easier than working with the trac-based fedora wiki.
A few of the
> > benefits:
> >
> > * Much easier uploading of images (especially multiple images)
> > * Easier syntax IMHO
> > * Built in versioning
> > * When editing within github itself, you can preview
without a page
> > reload. A simple thing, but very nice.
> > * Doc changes can be included with code pull requests.
("Hey, did you
> > forget to update the docs??")
> > * Doc updates/additions go through a review
> >
> > Thoughts?
> >
> > -Justin
> >
> > _______________________________________________
> > katello-devel mailing list
> > katello-devel@redhat.com <mailto:katello-devel@redhat.com>
> > https://www.redhat.com/mailman/listinfo/katello-devel
>
> _______________________________________________
> katello-devel mailing list
> katello-devel@redhat.com <mailto:katello-devel@redhat.com>
> https://www.redhat.com/mailman/listinfo/katello-devel
>
--
You received this message because you are subscribed to the Google
Groups "foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it,
send an email to foreman-dev+unsubscribe@googlegroups.com
<mailto:foreman-dev%2Bunsubscribe@googlegroups.com>.
For more options, visit https://groups.google.com/groups/opt_out.
