[prev in list] [next in list] [prev in thread] [next in thread]
List: fedora-docs-list
Subject: Re: Lowering the participation barrier for Fedora Docs
From: Zachary Oglesby <zach () oglesby ! co>
Date: 2013-11-14 15:33:02
Message-ID: CABypDWM=Lfy7Yjv6qJXdvATjkZnAA00FEdhVUexiiFnWRmHLVg () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
On Tue, Nov 12, 2013 at 9:50 AM, Eric H. Christensen <
sparks@fedoraproject.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512
>
> On Tue, Nov 12, 2013 at 07:30:59AM -0700, Pete Travis wrote:
> > I'm not at all proposing a migration or replacement of docs.fp.o or the
> > publican platform that lives there. It does its job well. I'm thinking
> > of second subdomain maintained by the docs group, with only small
> > articles. The kind of stuff that's lost on the wiki or in blog posts
> > now, because it doesn't fit into a guide. I agree that DocBook is
> > superior markup, but there are other considerations. Publican based
> > sites don't scale well for a large number of articles.
>
> Where would these articles exist? Would we have docs.fp.o, the wiki, and
> another place for documentation? Since we don't have a good search
> solution I suspect that adding more locations wouldn't make it easier for
> people to find stuff.
>
I think you hit the issue here. The wiki *should* be the proper location
for this kind of information, but do to the current state of the wiki this
good tutorials are lots in a sea of other information. If I recall
correctly fedoramagazine.org was intended to have a section for tutorials,
but I don't think that ever got off the ground.
>
> > Frankly, I want this to me different enough from business as usual to
> > attract people that may have already said "Oh, I looked into
> > participating in Docs, and I'm not interested in how they do things." I
> > envision that by providing an easy opportunity to contribute content and
> > get it published, we'll both serve our users better AND we'll have a
> > source of content for Guides, just waiting for more thorough markup. We
> > can educate people about the benefits of docbook, but we don't have a
> > captive audience - they have to come to us first.
>
> If people aren't interested in how we do things here then I'm not sure
> that there's much of a way to fix that. We use tried and true methods for
> getting the bits into the hands of the consumer. We've been through a lot
> of fail to get to where we are today. That's not to say there isn't room
> for improvement but I wonder if working on the education side of the house
> wouldn't be a good use of our time. Perhaps I can put together a video on
> creating a Publican document and doing some simple markup in DocBookXML.
>
> - -- Eric
>
I agree that DocBook is the best format for guides and long form
documentation, but I think there is value in having a way for people to
help without having learn Docs processes. In my opinion the issue is that
the Fedora Docs team work in a very different way when compared to other
distributions. Are focus has always been on the guides that are in
docs.fp.o, and we don't do much in the way for wiki based tutorials. If you
look at Arch Linux as an example of the other side of the fence, they are
focused on providing are large amount of information on many topics via
their wiki. I think the guides are important and don't think it would be
advantage to move away from that model, but giving people a means of
communicating smaller bits of information more efficiently is a good thing.
Maybe adding a section to the wiki menu for tutorials would help (and
finally fixing the search issues), but I don't know.
[Attachment #5 (text/html)]
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Nov 12, 2013 \
at 9:50 AM, Eric H. Christensen <span dir="ltr"><<a \
href="mailto:sparks@fedoraproject.org" \
target="_blank">sparks@fedoraproject.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div>-----BEGIN \
PGP SIGNED MESSAGE-----<br>
Hash: SHA512<br>
<br>
</div><div>On Tue, Nov 12, 2013 at 07:30:59AM -0700, Pete Travis wrote:<br>
> I'm not at all proposing a migration or replacement of docs.fp.o or the<br>
> publican platform that lives there. It does its job well. I'm thinking<br>
> of second subdomain maintained by the docs group, with only small<br>
> articles. The kind of stuff that's lost on the wiki or in blog posts<br>
> now, because it doesn't fit into a guide. I agree that DocBook is<br>
> superior markup, but there are other considerations. Publican based<br>
> sites don't scale well for a large number of articles.<br>
<br>
</div>Where would these articles exist? Would we have docs.fp.o, the wiki, and \
another place for documentation? Since we don't have a good search solution I \
suspect that adding more locations wouldn't make it easier for people to find \
stuff.<br>
</blockquote><div><br></div><div>I think you hit the issue here. The wiki *should* be \
the proper location for this kind of information, but do to the current state of the \
wiki this good tutorials are lots in a sea of other information. If I recall \
correctly <a href="http://fedoramagazine.org" target="_blank">fedoramagazine.org</a> \
was intended to have a section for tutorials, but I don't think that ever got off \
the ground. </div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div><br>
> Frankly, I want this to me different enough from business as usual to<br>
> attract people that may have already said "Oh, I looked into<br>
> participating in Docs, and I'm not interested in how they do things." \
I<br> > envision that by providing an easy opportunity to contribute content \
and<br> > get it published, we'll both serve our users better AND we'll \
have a<br> > source of content for Guides, just waiting for more thorough markup. \
We<br> > can educate people about the benefits of docbook, but we don't have \
a<br> > captive audience - they have to come to us first.<br>
<br>
</div>If people aren't interested in how we do things here then I'm not sure \
that there's much of a way to fix that. We use tried and true methods for \
getting the bits into the hands of the consumer. We've been through a lot of \
fail to get to where we are today. That's not to say there isn't room for \
improvement but I wonder if working on the education side of the house wouldn't \
be a good use of our time. Perhaps I can put together a video on creating a Publican \
document and doing some simple markup in DocBookXML.<br>
<br>
- -- Eric<br></blockquote><div><br></div><div>I agree that DocBook is the best format \
for guides and long form documentation, but I think there is value in having a way \
for people to help without having learn Docs processes. In my opinion the issue is \
that the Fedora Docs team work in a very different way when compared to other \
distributions. Are focus has always been on the guides that are in docs.fp.o, and we \
don't do much in the way for wiki based tutorials. If you look at Arch Linux as \
an example of the other side of the fence, they are focused on providing are large \
amount of information on many topics via their wiki. I think the guides are important \
and don't think it would be advantage to move away from that model, but giving \
people a means of communicating smaller bits of information more efficiently is a \
good thing. Maybe adding a section to the wiki menu for tutorials would help (and \
finally fixing the search issues), but I don't know. </div> \
</div><br></div></div>
[Attachment #6 (text/plain)]
--
docs mailing list
docs@lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic