Documenting Features
by Pete Travis
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_...
[2] http://fedoraproject.org/wiki/Category:Documentation_beats
--
-- Pete Travis
- Fedora Docs Project Leader
- 'randomuser' on freenode
- immanetize(a)fedoraproject.org
11 years
Re: Documenting Features
by Christopher Antila
-----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-----
11 years, 2 months
doxygen
by John J. McDonough
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
11 years, 2 months
Install Guide, install along side Windows?
by Chris Murphy
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
11 years, 2 months
Beat Writers for F19
by Pete Travis
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
11 years, 2 months
Docs meeting summary - 28 January 2013
by Pete Travis
====================================================================================================
#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.20...
.
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.
==================================================
11 years, 2 months
Fedora Docs Meeting Reminder
by Pete Travis
This is an automated message to remind you that we will be meeting at 1400
UTC in #fedora-meeting. Hope to see you there!
11 years, 2 months
Re: On the localization infrasturcutre of the Docs project
by Christopher Antila
-----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-----
11 years, 2 months