<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
On 05/28/2015 01:51 AM, Petr Hracek wrote:<br>
<span style="white-space: pre;">> On 05/28/2015 08:27 AM, Pete
Travis wrote:<br>
>> On 05/27/2015 08:57 AM, Adam Samalik wrote:<br>
>>> Hello everyone!<br>
>>><br>
>>> I would like to make a proposal about new project: a
website for Fedora developers.<br>
>>><br>
>>><br>
>>> === Why? ===<br>
>>> - Fedora does not have a page targeted on
developers like developer.ubuntu.com or developer.apple.com<br>
>>> - Developers have no place to find out about
interesting projects like Copr, Developer Assistant, etc.<br>
>>> - There is also no place with guides and help on
how to get things up and running<br>
>>> - Current fedoraproject wiki is not designed for
app developers, 'developers' on wiki essentially means Fedora
packagers<br>
>>> - There is no place for downloading (promoting)
Docker images and Vagrant boxes based on Fedora<br>
>>><br>
>>><br>
>>> === What? ===<br>
>>> Create a new page: developer.fedoraproject.org - a
new go-to place for app developers running Fedora.<br>
>>><br>
>>> The web page has would show beginners or advanced
users how to install a new features on Fedora and what to do if
they want to start developing something in Fedora.<br>
>>><br>
>>> The main categories could be something like these:<br>
>>> 1. Development tools:<br>
>>> - Vagrant, Developer Assistant, ...<br>
>>> - Which tools to use for development and how
they can help me<br>
>>> - explain WHAT the project is and HOW to get it
running<br>
>>> 2. Languages, technologies, runtimnes:<br>
>>> - Python, Ruby, Rails, Perl, ...<br>
>>> - Info about packages, the "I am a _ developer"
view<br>
>>> - explain WHAT the project is and HOW to get it
running<br>
>>> 3. Distribution/deployment:<br>
>>> - Copr, Docker, Openshift, ...<br>
>>> - How to get my project to people?<br>
>>> - explain WHAT the project is and HOW to get it
running<br>
>>> 4. Docker images, Vagrant boxes, ...<br>
>>> 5. Blogs<br>
>>><br>
>>><br>
>>> Petr Hracek and Josef Stribny and I are starting this
project and I will be the one responsible for it.<br>
>>><br>
>>> Do you have any tips, recommendations or expectations
about this project? Is there something you would like to see on
the page? Let's start a discussion!<br>
>>><br>
>>> Thanks!<br>
>>><br>
>>> Adam Samalik<br>
>>> Associate Software Engineer<br>
>>> Red Hat<br>
>> This sounds a lot like developer-focused documentation.
The docs team<br>
>> has been talking a lot about refocusing lately, and I had
it in mind to<br>
>> structure something that would provide appropriate
content to users,<br>
>> contributors, community members, and developers. It
would be great if<br>
>> we could combine efforts on this.<br>
> Hi Pete,<br>
><br>
> you are right. it is developer-focused documentation which
could<br>
> be actualized based of top projects which are developed
within Fedora.<br>
> Do you have any content already which was done by docs team?<br>
><br>
> Current top projects are I think Docker, Vagrant,
DevAssistant.</span><br>
<br>
No, we don't have any content in this area as far as I know. That
situation is a primary motivator for changing our tooling - the fact
that you're motivated to work up tooling and content independent of
Docs, without mention of a publican book, clearly demonstrates to me
that moving away from our Publican based site is a good choice. The
Docs team has experienced writers to help folks with the composition
process, and we want to enable the community at large to create
documentation that the current core writers don't necessarily have
time or domain knowledge for. The Fedora Project *should* have a
system in place where this kind of proactive idea can be put into
play by filing a ticket that says "Here is my repo of content,
please publish it".<br>
<br>
<span style="white-space: pre;">>><br>
>> There's a rough concept in place that I've been *slowly*
hacking at;<br>
>> take a bunch of git repos containing source markup (ie
one for each<br>
>> current guide, one for the python SIG, one with
fedora-infra SOPs, one<br>
>> for the Server WG and edition, you get the idea) and
process them. One<br>
>> step validates and pushes strings to zanata for
translation; another<br>
>> renders to html and extracts some metadata, another step
parses the<br>
>> metadata to create a menu / site structure. The steps
are run by<br>
>> buildbot (maybe taskotron, eventually) and triggered by
commits or<br>
>> fedmsg signals, so content creators can simply write out
a<br>
>> ReStructuredText article without getting concerned about
the publishing<br>
>> process and presentation.<br>
> This is what I missed in my first proposal. Translation to
different languages<br>
> can really be important for people which are not quite good
in English.<br>
><br>
> Like me;)<br>
><br>
>><br>
>> We've found that more people are willing to write -
whether it's API<br>
>> reference materials or general desktop usage - if their
domain knowledge<br>
>> can be the focus, and not documentation tooling and
processes.<br>
> I think it can be a separate page like
documentation.fedoraproject.org.<br>
> API is a different issue.<br>
> I htink that it can be covered and handled by
developer.fedoraproject.org<br>
> but developers which maintain API should also take care about
the page.<br>
></span><br>
<br>
My point here is that I would prefer an all-inclusive documentation
site. There can be separate sections for developers, users,
contributors - I had envisioned 'tabs' for these top level
distinctions, but design isn't my forte. The developer section can
use the same build infrastucture with the developer.fp.o domain on
top if you like. My concern is that now, when the Docs team is
actively working to address concerns around barriers to
contributing, that a separate site will fragment the potential
contributor base.<br>
<br>
<span style="white-space: pre;">> My first draft was create a
template for fedoraproject.org for rest pages which will be
developed in future.<br>
> Personally I think that current wiki [1] is not useless or
not readability for beginners and advanced developers.<br>
>> We also<br>
>> find that a git workflow enables better quality
documentation and<br>
>> fosters a sense of ownership and involvement, so the idea
is to meet<br>
>> halfway.<br>
>><br>
> Nowadays we have a GitHub repository [2] which does not
contain any contents.<br>
> Our idea is to use mechanishm like Jekyll and pages will be
actualized by pull-request.<br>
><br>
> [1] <a class="moz-txt-link-freetext" href="https://fedoraproject.org/wiki/Fedora_Project_Wiki">https://fedoraproject.org/wiki/Fedora_Project_Wiki</a><br>
> [2] <a class="moz-txt-link-freetext" href="https://github.com/phracek/developer-fedoraproject-org">https://github.com/phracek/developer-fedoraproject-org</a><br>
></span><br>
So we're generally on the same page here; git repo with content,
pull requests managed by content stakeholders, publishing via static
html generator. There's some sentiment against Markdown, so I'm
looking at RestructuredText and docbook to start - but the idea is
to support diverse formats, so someone doesn't have the opportunity
to refuse to contribute because they will *only* write in $markup or
will *never* write in $othermarkup. I missed the link[0] in the
first reply, sorry. Much of the work so far has been setting up
some reusable bits for creating buildbot factories, and I'm learning
to play with docutils lately.<br>
<br>
[0] <a class="moz-txt-link-freetext" href="https://github.com/immanetize/anerist">https://github.com/immanetize/anerist</a><br>
<br>
-- <br>
-- Pete Travis<br>
- Fedora Docs Project Leader<br>
- 'randomuser' on freenode<br>
- <a class="moz-txt-link-abbreviated" href="mailto:immanetize@fedoraproject.org">immanetize@fedoraproject.org</a><br>
<br>
</body>
</html>