docs February 2015

docs@lists.fedoraproject.org

15 participants
30 discussions

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by Pete Travis 23 Feb '15

23 Feb '15

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2015-02-23 from 14:00:00 to 15:00:00 UTC At fedora-meeting(a)irc.freenode.net The meeting will be about: An hour of docs folks talking about what they are working on and what they'd like to work on. More information available at: [https://fedoraproject.org/wiki/Docs_Project_meetings](https://fedoraproject… Source: https://apps.fedoraproject.org//calendar//meeting/371/

1 0

[Fedocal] Reminder meeting : Docs Office Hours ( Americas )
by Pete Travis 19 Feb '15

19 Feb '15

Dear all, You are kindly invited to the meeting: Docs Office Hours ( Americas ) on 2015-02-19 from 12:00:00 to 13:00:00 US/Mountain The meeting will be about: Office hours for Fedora Docs contributors. Stop in to #fedora-docs for help with writing documentation or just to schmooze with the Docs community. Bring your own cake. Source: https://apps.fedoraproject.org//calendar//meeting/434/

1 0

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by Pete Travis 16 Feb '15

16 Feb '15

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2015-02-16 from 14:00:00 to 15:00:00 UTC At fedora-meeting(a)irc.freenode.net The meeting will be about: An hour of docs folks talking about what they are working on and what they'd like to work on. More information available at: [https://fedoraproject.org/wiki/Docs_Project_meetings](https://fedoraproject… Source: https://apps.fedoraproject.org//calendar//meeting/371/

1 0

F22 Schedule and Beats
by Pete Travis 13 Feb '15

13 Feb '15

Greetings, The lull period of the release cycle is over[0], Fedora 22 has been branched from rawhide, and it is time to start thinking about beats. I'm adding asterisks to each name in the assignment column of the beats table[1], please remove the asterisk next to your name to confirm you can write the beat again, or add your name if you can help with the beat. According to the Docs schedule for Fedora 22[2], we are validating beat writers this week and beginning active recruitment for unclaimed beats next week, so please take a moment soon to update the table to help us keep on track. You can view the full release schedule and download ics files for your favorite calendar application too.[3] The individual beats pages will be cleared and opened soon. [0] https://lists.fedoraproject.org/pipermail/devel-announce/2015-February/0015… [1] https://fedoraproject.org/w/index.php?title=Category:Documentation_beats [2] https://fedorapeople.org/groups/schedule/f-22/f-22-docs-tasks.html [3] https://fedorapeople.org/groups/schedule/f-22/ -- -- Pete Travis - Fedora Docs Project Leader - 'randomuser' on freenode - immanetize(a)fedoraproject.org

2 2

[Fedocal] Reminder meeting : Docs Office Hours ( Americas )
by Pete Travis 12 Feb '15

12 Feb '15

Dear all, You are kindly invited to the meeting: Docs Office Hours ( Americas ) on 2015-02-12 from 12:00:00 to 13:00:00 US/Mountain The meeting will be about: Office hours for Fedora Docs contributors. Stop in to #fedora-docs for help with writing documentation or just to schmooze with the Docs community. Bring your own cake. Source: https://apps.fedoraproject.org//calendar//meeting/434/

1 0

The State of Publishing Documentation in Fedora
by Pete Travis 11 Feb '15

11 Feb '15

Hi all, I've given a lot of thought to our publishing situation. The current solution, using an unmaintained version of Publican on an unsupported Fedora release, is untenable. The site we have been maintaining in web.git is incompatible with current versions of publican, besides being massive and prone to breakage. We have been working towards a replacement, slowly. The proposed successor to web.git is an RPM based system where Publican creates SRPMs of the guides, Fedora's koji buildsystem builds packages from the RPMs, and a VM instance installs the package to build the site. Creating the SRPM would be analagous to the `publican build --embedtoc ...` from the old process, and when the VM installs the package, it does the `publican install-book` step of the process. We currently have the koji infrastructure in place, a mostly viable way for newly built packages to automatically be installed on the VM, and a functional but mostly vanilla site frontend. Along the way, I've identified a few caveats to this method, to which I'll add some general observations: - Each language of each release of each guide is a unique package. To publish anything new, we must coordinate with releng to have the package defined in koji. Releng is already overburdened. - Each language must have a separately maintained revision history. - The buildroot shared by koji and the VM required updated versions of publican and publican's dependencies, and now must be maintained there (which is currently not happening afaik). - None of the breakage problems we've dealt with in web.git will go away. Unusual language codes, bad draft procedures, wonky *_Info.xml issues, and whatever black magic that ends with my manually running sqlite invocations against the site db - that's all still there. - The site frontend needs to be completely redesigned from the ground up, and we have not demonstrated the motivation to see that through. There are intricacies here that we didn't discover from a straightforward following of the publican user's guide, and many subjectively frustrating surprises. - A publican website can only publish publican-friendly content. To the best of my knowledge, that means docbook only. Our contributor base is declining, and prospective contributors have consistently demonstrated a lack of interest in writing docbook. - A publican website does not provide an effective presentation of many smaller articles. I've been disagreed with on this point, and will concede that it's definitely possible to have 200 things under that F21 category, but I maintain that presentation in that way would be inimical to reader browsing. With all this in mind, I've decided to be honest with myself, and you, in saying that I'm not motivated to make the publican website frontend work. Something must be done to deal with our site's incompatibility with current Publican, but from a usage perspective, I feel like there's a very high upfront investment - and a moderate continuing investment in maintaining the el6-docs koji repo - with no substantial gain in the product delivered. For normal usage, we've simply replaced `publican build;publican install-book` with `publican package;koji build`. Rudi had initially volunteered to do *all* of the setup to make this work, but he's a busy guy and it really isn't fair to expect him to deal with that level of implementation for us. We've tossed around ideas in #fedora-docs, and in discussing it, I've developed a wishlist for an improved publishing platform: - We use release-based branches to maintain content for a given Fedora release. Anything committed to these branches is intended for publication, so that should happen automatically. - It should be simpler to make drafts available. If we can automate publishing on release branches, we can do the same with master. - We don't do as good of a job as we should with pushing and pulling strings from translation. Pushes and pulls could be automated. - There should be an effective way to publish and organize sundry articles. - The publishing platform should be able to process arbitrary markup formats. I think docbook is great, and publican does a good job with it, but there will be room for more contributions if that isn't mandatory. - The frontend of the site should be adaptable. docs.fp.o would ideally use the same design elements as other official Fedora sites for a more unified appearance. - Some validation on commits would be nice. The working theory at this point is to use a continuous integration system like Jenkins to automate builds. I've had a Jenkins instance running locally this week, with new builds triggered via fedmsg signals generated by our commits. This part works smoothly, with the exception of a fedwatch bug that I've crudely worked around, but triggers using python-fedmsg really wouldn't be too difficult. The infra folks are also working on a Jenkins setup, so there's potential to share experience and buildslaves. Turning that into a browseable frontend is more immediately viable than you might think; http://sourceforge.net/projects/jenkinscat/ is designed just for that and can be customized for our needs. Jenkins plugins to cycle strings from Zanata, or some other method, could come down the road. There's room for other enhancements, too. The CI idea is something I'm excited about, and motivated to work on. I'd love to spend that time working with others, if you're interested. --Pete -- -- Pete Travis - Fedora Docs Project Leader - 'randomuser' on freenode - immanetize(a)fedoraproject.org

1 0

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by Pete Travis 09 Feb '15

09 Feb '15

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2015-02-09 from 14:00:00 to 15:00:00 UTC At fedora-meeting(a)irc.freenode.net The meeting will be about: An hour of docs folks talking about what they are working on and what they'd like to work on. More information available at: [https://fedoraproject.org/wiki/Docs_Project_meetings](https://fedoraproject… Source: https://apps.fedoraproject.org/calendar//meeting/371/

1 0

[Fedocal] Reminder meeting : Docs Office Hours ( Americas )
by Pete Travis 05 Feb '15

05 Feb '15

Dear all, You are kindly invited to the meeting: Docs Office Hours ( Americas ) on 2015-02-05 from 12:00:00 to 13:00:00 US/Mountain The meeting will be about: Office hours for Fedora Docs contributors. Stop in to #fedora-docs for help with writing documentation or just to schmooze with the Docs community. Bring your own cake. Source: https://apps.fedoraproject.org/calendar//meeting/434/

1 0

I couldn't update web by publican 3 or 4 w/ install_book on CentOS 7 and Fedora 21.
by Tadashi Jokagi 02 Feb '15

02 Feb '15

Hello guys. I'm Joe as publisher in Japanese team. I couldn't update web by publican 3 or 4 w/ install_book on CentOS 7 w/ epel and Fedora 21. I also tried to use Publican 2 on CentOS 6. It got a wrong sidebar in generated contents. I want to update Release Notes for f21 in Japanese. Please help me or give me your advice. ... First, It's my operation. and I got this result. ===== Cut Here ===== Cut Here ===== Cut Here ===== Cut Here ===== [elf@localhost release-notes]$ publican install_book --site_config ../web/homepage.cfg --lang ja-JP WARNING: Unknow config key draft, ignoring. DBD::SQLite::db do failed: table books has no column named formats at /usr/share/perl5/vendor_perl/Publican/WebSite.pm line 498, <FH> line 14. DBD::SQLite::db prepare failed: no such column: books.formats at /usr/share/perl5/vendor_perl/Publican/WebSite.pm line 656, <FH> line 14. Can't call method "execute" on an undefined value at /usr/share/perl5/vendor_perl/Publican/WebSite.pm line 657, <FH> line 14. ===== Cut Here ===== Cut Here ===== Cut Here ===== Cut Here ===== It seems same this report. http://bit.ly/1z4opa4 Second. It's a generated book by Publican 2 on CentOS 6 w/ epel. Most of multibyte characters was broken. http://bit.ly/1z4oR8n I think updated book is good. because It was readable material. http://bit.ly/1z4pFKm Thanks. -- ----.----1----.----2----.----3----.----4----.----5----.----6----.----7---- Tadashi Jokagi / Live in Matsuyama city, Ehime pref. + E-mails: mailto:elf@poyo.jp (PC) mailto:elf2000@gmail.com (mobile) + Social sites: Twitter: http://bit.ly/elfTwitter mixi: http://bit.ly/elfMixi Facebook: http://on.fb.me/elfFacebook Spysee: http://bit.ly/elfSpysee + Web sites: To ehime... http://bit.ly/elfEhime

2 3

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by Pete Travis 02 Feb '15

02 Feb '15

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2015-02-02 from 14:00:00 to 15:00:00 UTC At fedora-meeting(a)irc.freenode.net The meeting will be about: An hour of docs folks talking about what they are working on and what they'd like to work on. More information available at: [https://fedoraproject.org/wiki/Docs_Project_meetings](https://fedoraproject… Source: https://apps.fedoraproject.org/calendar//meeting/371/

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs February 2015