Update on Virtualization Getting Started Guide
by Sandra McCann
Hi folks -
Just a short note as I promised to keep folks appraised of what I'm
changing here. It's a fairly short list:
- Removed references to older virtualization guides that aren't updated
yet.
- Merged virtualization products and tools chapters as there was overlap
there.
- Moved advanced concepts/tools into a new appendix.
So no information has been removed, just shifted so that the flow is in
line with the target audience (a person new to virtualization and/or just
looking to spin up a few VMs on their workstation).
I'm not sure how remove the 'draft' watermark?
thanks,
Sandra
8 years, 4 months
Personas for Fedora Docs
by Brian Exelbierd
I am restarting the discussion of Personas for Fedora Docs.
Personas are critical for scoping the level and style of writing we will do on some/all topics. The current draft set of personas is here: https://fedoraproject.org/wiki/Docs_Project_Focus
Before we dive into the various variant level personas that have been collected, we should think about whether we want to have more than a general set of personas.
For example, we could just write to several different users in general, and allow the specifics to shake out. I am personally in favor of a high level set of users who we can describe more fully relative to each variant/product situation. I’ve put some examples on the wiki page above.
I think this set of personas leaves us in a better position. We can easily present the site different to each kind of user. We can easily determine if we think a project requires a certain amount of knowledge, disclose that and then write only to personas that can handle it. We can also do audits at every level and focus ourselves on the real areas that each type of user gets stuck in.
This also gives our users a consistent person to “follow/shadow” in the documentation. Project level personas may feel like reading a novel where every time you start a new chapter (look at a new part of Fedora) all of the characters suddenly change.
I believe the best step forward is for us to decide if we want overall personas or project level personas and then to figure out who they are.
regards,
bex
8 years, 4 months
Fedora Docs - Barriers to Entry
by Sandra McCann
I promised to summarize my recent experience as a doc newbie and kickstart
a barriers to entry thread, so here go’s!
My Contributor Persona
Since it reflects on my experience, here’s my background. I’m new to Linux,
Fedora, Docbook, and git. If I got any newer, I’d still be in the eggshell
:-)
I do have XML documentation background so that made DocBook less painful.
A Baseline Example
I started out in the Fedora QA area, mostly because it seemed easier to
contribute at the time. As a QA tester, I could easily find a series of
test cases and almost exactly what I needed to do in each case to get pass
or fail on the test. These tests started out quite simple (download the
ISO and verify the size) and there were enough basic tests that I could
keep busy, mark things as passed, or in the rare occassion, log a bug.
(NOTE - logging the bug was only easy because it was a variation of an
existing bug so I could just clone and edit).
The parts of this experience that I think helped keep me involved and
motivated:
-
starting bar was very low and simple, with instructions.
-
contribution time could be as limited as 30 minutes and I’d have a
couple of tests done.
-
If I started something but couldn’t finish, I wasn’t holding anyone up
(completely independent tasks).
-
Ability to check something off as done on the test results wiki, get
some badges (yes, I’m that easily motivated :-)
-
A surprise callout thanks at the end of the project that listed ..erm… I
think the number of tests done. Imagine a simplified leaderboard approach.
-
Could build up my experience (ability to run more advanced tests) at my
own pace, while still contributing on the tests I already knew how to run.
And obvious progression path existed.
-
No real commitment - I just pop in when I can, run a few tests, feel
good, go back to the day job. I know I’m not the only one running the
tests, so if I can’t contribute for a test cycle or three, I’m not holding
anything up.
My Fedora Docs Experience
Now we get to my shift over to docs. I poked at the doc project wiki, and
while the front page seems quite clear, I stumbled off and on after that. I
lurked a bit in irc, then eventually introduced myself and got a few
pointers on what to learn (pointers to a git tutorial and docbook etc). I
floated around for some time after that and didn’t really get involved
until someone mentioned the virtualization getting started guide needed
work. Since I was new to Fedora and all things Linux, I didn’t feel
confident to volunteer prior to this, but I’m having to write about VMs in
the day job so this seemed a good logical extension (aka something I knew a
little bit about). After that, it was fits and starts and fubars with git
(some quite recent :-). I think I’ve got it down now, but time will tell!
Fedora Docs Barriers to Entry
After that long-winded tale, here’s what I think the barriers are, at least
for someone with my experience:
-
No simple way to come in, give an hour or two, and disappear for a month.
-
“mentorship’ requires a live person and can be difficult to connect to
when first starting out.
-
Steep learning curve for git and/or DocBook if you don’t have prior
knowledge.
-
Must have technical knowledge of the subject matter.
-
Confusing set of information on the doc projects wiki*
For the doc projects wiki - I found different paths through it, whether I
was starting from the main docs project page, or googling for information
and landing on some random page. I also didn’t find out about the
fedorapeople site until grundblom started using it (my fellow traveller on
the doc newbie path in the virtualization getting started guide).
I will also say it helped very much to have another new doc contributor
with me along the way.
Anyway, that’s my tale for today!
Sandra
8 years, 4 months
Self Introduction: William Moreno Reyes
by William Moreno
Hi
This is my first mail to this list, I will like to help with docs, maybe
written a Beat, or something for the Fedora Cookbock.
- Name: William Moreno Reyes
- Location: Managua, Nicaragua
- Login: williamjmorenor
- Language: es-ES, en-US
- What other projects or writing have you worked on in the past?
I learned the basics of Publican / Docbook in Fudcon Managua in and
workshop with jsmith, and I have been testing since Fudcon, my bigger
project at now is to import to publican/docbook the ERPNext manual:
https://github.com/williamjmorenor/manual_erpnext_publican
I will try to package erpnext once the v5 is available in the master branch
but this is a packaging topic and not a doc topic :).
But thanks to this I am very familiar with Publican and DocBook :)
I write a blog, most is in Spanish: http://otroblogdegnu-linux.blogspot.com/
- What level and type of computer skills do you have?
I am Fedora user since F17, I am formally a certified public accountant,
but I manage well a Fedora Workstation both in graphical mode as working
from the terminal.
- What other skills do you have that might be applicable?
I am Fedora Ambassador, Packager, also I am in the Video and Desing teams
and translate some strings in Zanata.
- What makes you an excellent match for the project?
As I have not formal education in IT every task I undertake in Fedora term
learning something, often after hours of searching and reading, at the end
try to finish the task by writing a post about what finished learning, I
would like to help document things in a user view, not a technical
standpoint,
- GPG KEYID and fingerprint
*pub* 2048R/DDAA58C7
<https://pgp.mit.edu/pks/lookup?op=get&search=0x4A5C92ACDDAA58C7>
2015-05-14
*uid* William Moreno Reyes (Fedora Project)
<williamjmorenor(a)fedoraproject.org>*sub* 2048R/044661A3 2015-05-14
8 years, 4 months
In need of remedial git/ssh help
by Sandra McCann
Hi folks -
I'm attempting to clean up the virt getting started guide but I can't
get...started :-P
Looking at this page:
https://fedoraproject.org/wiki/Docs_Project_work_using_git
I'm trying to use ssh instead of https to clone the repository but I get
the following error:
git clone ssh://
mccann2(a)git.fedorahosted.org/cgit/docs/virtualization-getting-started-guide.git/
Cloning into 'virtualization-getting-started-guide'...
fatal: protocol error: bad line length character: Inva
So then I tried without the username, and I get this error:
[sandra@f21 test]$ git clone ssh://
git.fedorahosted.org/cgit/docs/virtualization-getting-started-guide.git/
Cloning into 'virtualization-getting-started-guide'...
Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
Any clues what I may be doing wrong?
Thanks,
Sandra
8 years, 4 months
