Release Notes in AsciiDoc, first draft
by Robert Kratky
Hi all,
Apologies for dragging my feet with this.
I converted the current version of F26 Release Notes. You can see the
result in https://pagure.io/release-notes/branch/f26-adoc
To check out the branch on local, run:
$ git checkout --track origin/f26-adoc
To build the doc using AsciiDoctor, run:
$ asciidoctor -a toc -n master.adoc
(and open the resulting master.html file)
I think the result is pretty good. I hope to have fixed all problems
that came up during the conversion. While doing so, I also fixed and
improved some mark-up and removed all hard line breaks in text
paragraphs.
If you want to fix stuff in the content of RtN, I suggest you work
with the AsciiDoc sources from now on to avoid the need to port
changes from DocBook to AsciiDoc again.
One thing I wasn't sure about: the DocBook original includes a bunch
of empty chapter files (areas that didn't receive any notes for F26).
I decided not to include them. I'm not sure why we carry them around.
But please, let me know if you think they should be in the repo.
Robert,
Robert
6 years, 8 months
Doc-reboot - added translation support with po4a
by Jean-Baptiste
Hi,
here is a Pull Request adding:
* adoc to pot
* pot -> po (it updates existing translation files)
* po -> adoc (we have to agree on a threshold, I used 0 by default)
* zanata push/pull
https://pagure.io/docs-reboot/install-guide/pull-request/2
I add my name as point of contact on the script, but I reuse most of
Brian's work.
Please note the translators also need to translate _topic_map.yml, but I
assume we should probably move this file into "en-GB". Can we do this?
https://pagure.io/docs-reboot/install-guide/issue/3
I'm afraid my laptop is crashing too much at the moment to go really
further, this code needs a little more testing, but I'm confident it's
going to work very fine.
We'll have to add language switch (please use a more obvious location
than what we have for websites ;)).
Have a nice day,
--
Jean-Baptiste Holcroft
6 years, 8 months
Docs Reboot update and test site
by Brian Exelbierd
Howdy,
Test Site: https://bex.fedorapeople.org/fedora-docs-web/index.html
Details below ...
We've made some progress on our docs reboot site. As you know our goal
is August 1(ish) so your feedback is very very appreciated. When
considering issues, please think about what is required to launch versus
nice to have later. Please report issues where indicated below, if
possible.
## Convert Documentation to AsciiDoc
We have converted two of the three books we want to move to AsciiDoc.
We have put the sources in a new set of a git repositories to make a
"clean break."
Installation Guide: https://pagure.io/docs-reboot/install-guide
System Administrators Guide:
https://pagure.io/docs-reboot/system-administrators-guide
These repositories are ready for your content PRs. For now, please
submit PRs against the master branch. Once we are further down the road
we can really differentiate the F26 and master branches. Issues against
the content are also welcome (see below).
The Release Notes are being converted now and I will send an update (if
someone else doesn't) when they are done.
## Publish the AsciiDoc content using AsciiBinder
A basic publishing repository has been setup along with an html output
repository.
Publishing Code: https://pagure.io/docs-reboot/docs-fp-o
Built Output: https://pagure.io/docs-reboot/fedora-docs-web
Test Site: https://bex.fedorapeople.org/fedora-docs-web/index.html
Please report general issues and appearance issues against the Code
Repo. Content issues should go against the content repos.
I am in the process of adding a project plan to the README in the code
repo.
Feedback appreciated.
regards,
bex
6 years, 9 months
Re: [Developer-portal] Re: Updating fedora wiki
by Pavel Valena
----- Original Message -----
> From: "Brian Exelbierd" <bex(a)pobox.com>
> To: docs(a)lists.fedoraproject.org, developer-portal(a)lists.fedoraproject.org
> Sent: Monday, July 24, 2017 11:18:21 AM
> Subject: [Developer-portal] Re: Updating fedora wiki
>
> +developer-portal(a)lists.fedoraproject.org s this is not a docs
> maintained resource.
>
> On Fri, Jul 21, 2017, at 11:31 PM, Paul W. Frields wrote:
> > On Fri, Jul 21, 2017 at 04:45:56PM +0200, Brian Exelbierd wrote:
> > > On Fri, Jul 21, 2017, at 03:10 AM, Ben Kelsey wrote:
> > > > Hi,
> > > > I was trying to update a page at
> > > > https://fedoraproject.org/wiki/HOWTO_Setup_Android_Development and it
> > > > says I need to be added to a group to do this. Can someone add me to
> > > > the required group. My user name is bkelsey.
> > >
> > > Hi Ben,
> > >
> > > I think the page would be way more useful if it was on this site:
> > >
> > > https://developer.fedoraproject.org/start.html
Thank you Bex.
Yes, that seems to be the type of content we're looking for.
> > >
> > > Would you be be interested in porting it over?
> >
> > I agree with bex... OTOH be warned that the developer.fp.o site isn't
> > quite as straightforward as to how you craft pages for it. I just
> > went through that gauntlet to create:
> > https://github.com/developer-portal/content/pull/203
True. It can be challenging for some people. That's partly because the guides (and docs) are missing or outdated. Sadly, there are no people to fix that (sorry). Any help is greatly appreciated.
On the other hand, we expect the developers themselves to create and maintain the Developer Portal content, so some level of experience (with git, Markdown, etc.) is expected. Alternatively you can gain the experience in the process, as we'll gladly help you with the PRs.
> > Not impossible by any means -- just more complex than its own docs
> > indicate on how to make changes. (Mumble mumble, something about the
> > cobbler's kids' shoes.) ;-)
From my POV updating already existing content is quite easy. Please let me know what you consider complex in doing so, because we really need to make it simple and straightforward.
Adding a completely new content can be hard, because (as of now) you need to build and view the website locally, and that is not fully automated yet. There are some help scripts, READMEs, and tools in our repositories[1][2] though (that's missing in the contributing guide too :/) and we're on irc (#developer-portal @Freenode) if you run into some obstacles.
Note that the PR above adds a content, that IMHO is documentation-like, which is a NO-GO for Developer Portal, so that needs to be fixed too (not to mention the Markdown there needs quite a bit of polishing, which I do not consider complex at all).
Regards,
Pavel
[1] https://github.com/developer-portal/website/
[2] https://github.com/developer-portal/tools/
> >
> > --
> > Paul W. Frields http://paul.frields.org/
> > gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
> > http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
> > The open source story continues to grow: http://opensource.com
> > _______________________________________________
6 years, 9 months
About applying for Doc Project
by 小木
Hi,
Good morning！
I am a Linux enthusiast from China, has nearly 2 years of experience in Linux, and obtained RHCE, recently discovered your organization document project. All along, I would like to be able to participate in the Linux community documentation and related work, so I hope to join the Doc Project, for the development of Fedora to do something. Hope to get your organization's reply and approval.
Thank you!
MU
July 18, in Zhengzhou, China
6 years, 9 months
Converting DocBook to AsciiDoc
by Jaromir Hradilek
Hello everyone,
A few months ago, Ryan (t3rm1n4l) sent an email to this mailing list to
inform the group that he had converted the System Administrator's Guide
to AsciiDoc [1], and to look for people interested in helping him to
make it modular. To convert it, he used docscii [2].
docscii is a command line tool that takes DocBook source code and
converts it to AsciiDoc. Unlike some other tools, it is familiar with
the directory structure created by Publican, can work with the .ent
files, and preserves original file names rather than producing one large
AsciiDoc file with everything in it. It is written in Go. Unfortunately,
the upstream project does not seem to be active any more, with the last
commit being over four months old.
I think this tool has potential and believe that no matter how we decide
to create documentation in the future, we will end up using AsciiDoc and
having our old documents already in this language will allow us to focus
on the important thing: the content, not the markup language. To help us
refine the tool, I therefore created a fork of the upstream repository
in Pagure and committed a few minor fixes (I am not a Go programmer though):
https://pagure.io/fedora-docs/docscii/
If this interests you, let me know if you would like to get permissions
to commit to this repo, and please report any issues you find there [3].
If we try, I think we can make the conversion nearly perfect. I also
believe the original author is subscribed to this mailing list and I can
still see them as a member of the fedora-docs group in Pagure so there
is a chance some of the changes might eventually make it back to the
upstream version of the tool.
Thank you,
Jaromir
Links:
[1] https://pagure.io/fedora-docs/asciidocs-sysadmin
[2] https://github.com/clayts/docscii
[3] https://pagure.io/fedora-docs/docscii/issues
6 years, 9 months
Open Help Conference
by Shaun McCance
Hi all,
I occurs to me that I never sent an announcement for Open Help to the
team. Many of you know that I run a conference each year that focuses
on documentation and support in open source and open communities. It's
coming up next month, August 12-16:
https://conf.openhelp.cc/
There's a two-day conference with a mix of presentation and open
discussion. The conference is followed by three days of team sprints
for any team that wants to take part. Teams are free to run their own
sprints, or use me as a facilitator.
I know that is very close to Flock, but I wouldn't be doing my job as
an event organizer if I didn't let you all know.
Also, it turns out I'll actually be at Flock this year. I hope to see
some of you either at Open Help or Flock.
Thanks,
Shaun
6 years, 9 months
