docs January 2013

docs@lists.stg.fedoraproject.org

23 participants
45 discussions

Documenting Features
by Pete Travis 04 Mar '13

04 Mar '13

Hey guys, I've been reading the Feature discussions on devel@ today, and an idea came to mind. A process for documenting accepted Features would help prevent major changes from slipping through the cracks. Here's what I came up with so far; I think we can hammer it into something useful: Accepted Features[1] will be listed in a table roughly analogous to that used for Release Note Beats[2]. The table would have columns for the Feature name, a docs volunteer, and developer contact, as well as others reflecting the Feature documenting workflow. A set of guidelines for the docs volunteer covering a feature will come along with the table. The set of tasks to be juggled might include: - Establishing an appropriate developer point of contact to aid in documentation. Note that this isn't always the feature owner. - Ensuring the content of the Feature is understandable by a hypothetical average user. - Working up a basic guide to implementing the feature, if applicable. - Creating an entry for the Feature in the appropriate Release Notes beat. - Checking existing guides for impact caused by the new Feature, filing bugs as needed, and assisting the guide owners in updating as appropriate. A defined process like this will help split up the workload caused by feature churn and cut redundant efforts by providing new information for multiple published works. Your thoughts? [1] http://fedoraproject.org/wiki/Releases/19/FeatureList#Fedora_19_Accepted_Fe… [2] http://fedoraproject.org/wiki/Category:Documentation_beats -- -- Pete Travis - Fedora Docs Project Leader - 'randomuser' on freenode - immanetize(a)fedoraproject.org

4 4

Re: Documenting Features
by Christopher Antila 29 Jan '13

29 Jan '13

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi: On 30 January 2013 00:29:47 pete wrote: > I've been reading the Feature discussions on devel@ today, and an idea > came to mind. A process for documenting accepted Features would help > prevent major changes from slipping through the cracks. Here's what I > came up with so far; I think we can hammer it into something useful: Good idea. I suggest we revise and formalize the beat-writers' workflow with a process that uses the feature pages. > Accepted Features[1] will be listed in a table roughly analogous to that > used for Release Note Beats[2]. The table would have columns for the > Feature name, a docs volunteer, and developer contact, as well as others > reflecting the Feature documenting workflow. I'm not sure we need another table. We already have developer contacts for many of the Release Notes beats. What we could do is revise the "Release Notes" and "Documentation" sections of the Feature page after a beat writer moves it into a particular beat, or a QA contact moves it into a particular Guide. What other information did you imagine we would put in this table? > A set of guidelines for the docs volunteer covering a feature will come > along with the table. The set of tasks to be juggled might include: > - Establishing an appropriate developer point of contact to aid in > documentation. Note that this isn't always the feature owner. Between the existing developer contacts and the feature owner, do you think we will need another? > - Ensuring the content of the Feature is understandable by a > hypothetical average user. This is something beat writers (should) already do. We saw in the F18 cycle that it's not necessarily the case, but a standardized workflow will help! > - Working up a basic guide to implementing the feature, if applicable. In September, I wrote an email to the Docs QA list with a draft process to get features into applicable Guides.[1] I think we only partially did this for Fedora 18, and I don't remember any further developments in this area. If you're suggesting a Release Notes supplement, where we describe how to use new features, that's something entirely different. > - Creating an entry for the Feature in the appropriate Release Notes > beat. Beat writers. > - Checking existing guides for impact caused by the new Feature, filing > bugs as needed, and assisting the guide owners in updating as > appropriate. See above about QA contacts. Also, the Release Notes QA contact (zogelsby) could check that all the Feature pages have been documented in the appropriate beat. Maybe he already does! > A defined process like this will help split up the workload caused by > feature churn and cut redundant efforts by providing new information for > multiple published works. Your thoughts? As it stands, I think what we need most is more people who are both consistent across releases and have the time to do a good job. A clearly-defined working process will help beat-writers get on board in the first place, and remember what to do (and how easy it was!) when it comes time to repeat in the next cycle. Christopher [1] https://lists.fedoraproject.org/pipermail/docs-qa/2012- September/000103.html -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRCH2qAAoJEGpo1cWDqVnYYkYP/1PDfjqZDuqV/5qWvgVgxT/P TVJCw7p5SP1YUyNtKhDkXdikdm1iY+xIoUSCSgo5v5nHmP+4nex1pjBzQFdouYYA kS/leP71rHSZqg01t79i1inPzC9ukwtdEGwqeleBYHtQ/aWo273TJ9EWSzrb5n+t xeyWAnrDGdpZppIm0qIlXd2e9rAVFt1TMf4OeoSNzxeZGvBsZZnQXhzBRwcYdhu7 dm4B4HLCiFd7uTuT+HfSDvIC4U+Rthg5lwBRYay0JCYL9W/PXSqWx+heU3yApTsP 9gO7+vJRZ9/r4ljWph6mVpl2+9/S+xefu7JtVNCxgK4mjKkK2W/EMunymB98IFgi 57qS8rcIqpAWMo0KcS9DsLpuyxjq/cykkekwnef54AA0iKurREYC6tB+pgooIeNa MjkPdT7E99dewGPGXwTu1EqcJBvcuLkVUJKgC0vKXSeBXoPQvcVgXTfWD1WLAt6F q2d4WiTxunCzvrB0qLq51TTm8rGKKPDNweOQPWmcL3Hty7ok/vFrBqZAfnRt+I17 cPBm59CfpW2zNaCK2gWTX+S9y9sYe6UDTiewuPdSlbz38impynUiMYvcvidErsxR PtmJCIxz1Gg3R5cLW1C/rHJBcvhy/NmqCLKu+c2Gvo34TQgAjTo7+NEqEz34SaIM 2OsPbbjR92Om9+KeHUq/ =x1HS -----END PGP SIGNATURE-----

2 1

doxygen
by John J. McDonough 29 Jan '13

29 Jan '13

Has anyone gotten doxygen to work on F18? It is currently a blocker for doc-publican-rpm. the pdf output is the issue. Apparently, doxygen isn't that great about "Requires" and Koji can't really check runtime requires. d-p-r got around this in earlier versions by requiring texlive-utils. However, in F18, texlive-utils is gone, apparently replaced by dozens and dozens of texlive-xxx. The first few were relatively easy to figure out, but the error messages have gotten cryptic enough that I can't seem to sort it out. The F17 RPMs are on my fedorapeople. This RPM puts the document in /usr/share/doc/basename-version I want to do a lot more testing before I call it soup. If some folks would like to test it, and especially review the source diffs http://tinyurl.com/a2d955v it would be much appreciated. --McD

1 0

Install Guide, install along side Windows?
by Chris Murphy 28 Jan '13

28 Jan '13

Hi, I see a section for dual-boot removing Fedora on Windows computers. I do not see a section at all for how to install Fedora on a system that contains Windows already. Is anyone working on this? Currently, I find it distinctly non-obvious how to proceed for a new user to newui. The earlier option to click on an existing Windows partition and shrink it, has been removed from 'guided' autopartitioning because the shrink option left Windows with only 1GB of free space, essentially rendering it not usable. So now, Windows users installing Fedora along side Windows, must use Manual Partitioning. Windows appears under +Unknown so first they have to find the partition, click it, and then go to the right side and change its capacity to shrink it and make room for Fedora. Each of those steps I think require increasing quantities of imagination to guess the next step to make this work. But a short amount of documentation, a 1/2 page, would go a long way to making this a lot easier for people. Chris Murphy

1 0

Beat Writers for F19
by Pete Travis 28 Jan '13

28 Jan '13

Hey folks, Our release notes process begins with writing a `beat`. We chop changes in the distribution onto chunks of manageable scope, and volunteer to write about a beat we're familiar with. We keep a table at http://fedoraproject.org/wiki/Category:Documentation_beats to track beat assignment, although anyone can add content to any beat. During the last week, I reset the columns used to track publishing status and added an `*` to everyone's name on the list. The asterisk has been our convention to indicate an unconfirmed beat assignment or developer contact. If you currently contribute to a beat, or you'd like to, please stamp your name in the table. Using the timestamp signature "~~~~" will help differentiate stale assignments from new ones. Don't wait to see if someone else will claim a beat if you have an interest in that space! More hands makes for light work. After a suitable length of time, I plan to clear out the unconfirmed beats and replacing the old username in the table with "unassigned". --Pete Travis - Docs Project Leader

1 0

Docs meeting summary - 28 January 2013
by Pete Travis 28 Jan '13

28 Jan '13

==================================================================================================== #fedora-meeting: Docs Project Meeting - Agenda: https://fedoraproject.org/wiki/Docs_Project_meetings ==================================================================================================== Meeting started by randomuser` at 14:01:08 UTC. The full logs are available at http://meetbot.fedoraproject.org/fedora-meeting/2013-01-28/fedora_docs.2013… . Meeting summary --------------- * Roll Call (randomuser`, 14:01:33) * Follow up on action items (randomuser`, 14:06:27) * pkovar filed https://bugzilla.redhat.com/show_bug.cgi?id=902500 and welcomes comments (randomuser`, 14:08:29) * Publishing docs with Publican 3 and koji (randomuser`, 14:24:32) * Sparks is working on it (randomuser`, 14:24:43) * outstanding BZ tickets (randomuser`, 14:24:58) * LINK: http://tinyurl.com/lbrq84 (randomuser`, 14:25:10) * Beats status (randomuser`, 14:31:14) * ACTION: randomuser to mail docs list about confirming beat assignments (randomuser`, 14:40:11) * zanata (randomuser`, 14:42:49) * LINK: http://lists.fedoraproject.org/pipermail/docs/2012-July/014465.html (pkovar, 14:47:47) * LINK: http://lists.fedoraproject.org/pipermail/docs/2012-July/014465.html (Sparks, 14:48:19) * We need to establish a feedback loop with transifex (randomuser`, 14:56:16) * ACTION: pkovar to test push to tx, report problems (randomuser`, 14:59:23) * Open Floor Discussion (randomuser`, 15:01:58) Meeting ended at 15:03:01 UTC. Action Items ------------ * randomuser to mail docs list about confirming beat assignments * pkovar to test push to tx, report problems Action Items, by person ----------------------- * pkovar * pkovar to test push to tx, report problems * **UNASSIGNED** * randomuser to mail docs list about confirming beat assignments People Present (lines said) --------------------------- * randomuser` (65) * pkovar (45) * Sparks (24) * bcotton (8) * zodbot (5) * jjmcd (5) * nb (1) * bcotton_ (1) ================================================== After the meeting, in #fedora-docs, nb pointed out that our delay with the release notes nearly caused a slip with F18. Given the lengthy cycle of the F18 release, this shows we need to put a lot more effort into the Release Notes. nb is going to make an effort to give an opinion of our schedule for the next meeting. Any other suggestions on improving the Release Notes workflow are welcome. ==================================================

1 0

[Bug 902500] Publican-based books in GNOME Shell
by Red Hat Bugzilla 28 Jan '13

28 Jan '13

Product: Publican https://bugzilla.redhat.com/show_bug.cgi?id=902500 Pete Travis <me(a)petetravis.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |me(a)petetravis.com -- You are receiving this mail because: You are on the CC list for the bug. Unsubscribe from this bug https://bugzilla.redhat.com/token.cgi?t=i30c49uhn2&a=cc_unsubscribe

1 0

Fedora Docs Meeting Reminder
by Pete Travis 28 Jan '13

28 Jan '13

This is an automated message to remind you that we will be meeting at 1400 UTC in #fedora-meeting. Hope to see you there!

1 0

UEFI based systems, minimal boot media typo?
by Chris Murphy 27 Jan '13

27 Jan '13

http://docs.fedoraproject.org/en-US/Fedora/18/html/Installation_Guide/Makin… 3.3.1 refers to a efidisk.img file in the images/ directory on the Fedora 18 installation DVD. This file doesn't exist. There is an efiboot.img, but I'm not sure if that's what should be referenced instead. https://bugzilla.redhat.com/show_bug.cgi?id=904292 Chris Murphy

1 1

Re: On the localization infrasturcutre of the Docs project
by Christopher Antila 25 Jan '13

25 Jan '13

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hello: I would like to take this opportunity to remind everybody that, since we are indeed Fedora, we are large and highly visible, and we should set an admirable example of problem-solving for other free software communities to follow. Language like this... > Right now, a different platform is being shoved down the L10n team's > throat without any public discussion or effort to work on top of > what we have. ... seems very aggressive. Furthermore, the "shoved down people's throats without any public discussion" figure of speech is now a cliché in technology circles, and is more likely to discourage than encourage discussion. > This is just wrong. Nothing is ever "just" wrong or right, and that's why there is disagreement. I suggest we speak in ways that encourage and remind us that disagreement leads to better solutions. It's quite easy: what about "I feel this is wrong," or even "I feel this is just wrong." > We're Fedora, we can do way better than this guys. What about the people who do not choose to be "guys?" - -------------------------- I don't understand this situation either, and--like Dmitri--I have been wondering for a while why the Guides on Zanata remain there. On the other hand, I am upset with how quickly this situation seems to have turned into a covert "turf war" between Transifex and Zanata. I know Fedora has a historic relationship with Transifex, and I think Dmitri is right to feel upset if he feels the Docs Project hasn't provided an adequate explanation for the switch. But ultimately, we all wish to produce the best documentation, and this is why some Guides are on Zanata. Christopher -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRAwouAAoJEGpo1cWDqVnYhIcQAKFh5/IM4poLyAeAky83y4WB QsepUiQSheF/td6z41d7zMK8J3DZ7XAZNQMD4JyZ6mVWH13KCrOCPqFkj4mCtRdd YfxMIphZ4exy7cGm0bhLmsPUsGAp9OWGkzl/UrI9JhKTJLdETIW8lFu+egD1uRz1 NtS5ERC4ZU2y+UCBU2MgQeLqG5OJ8HA5mbFiaNAqDSkxfbTIalMmjoAJbwV3IQwO x+LaR4ivgu9GAr7mHSrVhV5eTIOKKQL6krYEw/QvLjbaPs09QwpcnnjPws4IQmtu Ans5U9BpzN+A/6CcXBgRb25Sm6Lq4cT2Bw0FMc+ncTED/LEoKYRaosA8h42CQHVS 24OuGmN51Nx5wfBpONQEu50TodPYkVpmkkPJWOONaoqZaCodsYTpJQr5+KaNcYln 3XX08S6J+of1DmbUJvXuxNT7/hBGWRwnwGd4YQ8uiwr+mM0Mw+162ldc2indvo+i TM/QzfbbZYM3UYR4aa6BUTwbKhhVDmoD4fqimfyyYyPx5XvyaZPPFn0x8I6KkEiX sA5/OLbjmuuWjdAW1f+VRSr/5553+MuCdjLufjcf7av51J+qlUBk4KaxwQ1IX4jX nqzHygZY5fqtH5xe5ChZ349Xk18q9OaYuLSP/MV+kRamCoVqXh1oZg/eXU2DTGH0 sXEI2DWAe+P+zzK1XljO =4iPE -----END PGP SIGNATURE-----

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 January 2013