[ Dekstop Help ] First Contributions - Lesson Learned

[Greg Beam]

Hello All,

Warning, This Is A "Long Email" .. here we go :-)

I'd like to thank the folks in ubuntu-docs IRC, dsmythies, shaunm__,
godbyk, knome, bkerensa, (sri if I've left anyone out) for helping me
with the problems I ran into. If not for them, I would still be in a
tail spin wondering what went wrong and how do I fix it.

I thought I would share with you the problems I had with 2x MP's, 1x MP
update and simple bug fix. The hope is we can prevent other new
contributors falling into the same holes. Some are systemic while others
were clearly blunders on my part.

Before I start, this is NOT to intended to be negative in any way.
Critical yes, but in a positive light. We need to fix a few things to
prevent others from having the same issues. 

For the experienced dev's, contributors and editors, this may be white
noise, where the would be new contributor is left saying "this is not
worth the pain!!".

That said;

A plan to make a plan would be a good start ...

Core Reference:
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation

While the Wiki Home and Join sections are important, the focus of my
comments today are on System Documentation Tabs.

- Tasks Tab:
------------
* The last update was in 2012. I found the current task list through
talking with team members in IRC ubuntu-docs. 

- Repository Tab:
-----------------
* This page needs an overhaul. It uses Natty and Karmic as examples, and
points users to Apps >> Accessories >> Terminal. That should have
sounded alarm bells, but it didn't. Blunder #1 on my part.

* The biggest issue was local repository setup methodology. Long story
short, if we use the Advanced method, which is recommended in the
standard method section to speed up downloads, one can only a single MP
or bzr bundle at a time. This was not obvious to me at the time. Those
new to working in bzr or in a bzr Distributed + Gatekeeper work flow may
or may not put that together.

* Only after several long conversations in IRC, I finally figured out I
was causing all sorts of problems for the commiters, and sending the
wrong data to launchpad.

knome gave me a solution that works. Further discussion with godbyk
confirmed it to be a commonly used. The work around is as follows:

.. bzr branch lp:ubuntu-docs
.. cp -R ./ubuntu-docs ./ubuntu-docs-lp12345 
.. cd ubuntu-docs-lp12345 
.. do work ..
.. commit --fixes lp:12345 -F "./commit-notes.txt"
.. bzr push lp:~ki7mt/ubuntu-docs/lp1234-fix

To work a second bug, before the first MP is merged:

.. cp -R ./ubuntu-docs ./ubuntu-docs-lp6789

repeat work, commit, bzr push

* If I need to send updates or corrections, I merely cd to the correct
location, fix the issue, commit, and push it up again.

- Editing TAB:
--------------
* If the way forward is Mallard for Desktop Help, we need to overhaul
this page completely.

- Checking TAB:
--------------
* Same problem here, it is not setup for Mallard. The build instructions
do not work at all as stated.

* I think using yelp (plus /path/to/ubuntu.xsl) is a very good tool, but
we need to document it's proper use for Desktop Help. I did not use
ubuntu.xsl, as I was unaware of the need, which resulted in allot of
re-work. 

* Using the status tags could be very useful. I was told we're not using
them for any kind of tasking or review process. run make status, which I
tried, does not work, build/status files are generated. I used old
faithful; cd ./C && grep -R 'status="some-cool-condition"' which I found
useful, until I was told they are not maintained.

- Submitting TAB:
-----------------
* Both method stated only work for one MP or bundle > some-cool-fix.txt

* If you followed the Repo TAB, your stuck with that branch until you
can update / pull the merged changes. Doing any additional commits /
work will cause issues. This resulted in blunders/{4....9}. I should
have picked up on the fact I was using a shared-repo, but I didn't until
it was too late.

- Other Suggestions:
--------------------
* We need a Mallard specific styles guide, with Ubuntu Desktop examples,
the more the better.
* We need to published work flows that new team members can easily
follow.
* We need copyright policies clearly stated with examples.
* We need Unity specific .stub files and the method to generate pages.
* We need guidance on how or when to use admonitions.
* We need guidance on Gnome to Unity separation, what, how much, and by
when, the old W3 thing (Who, What & When).
* We need priority tasking. We know the deadline, but for us new folks,
its not clear how we can help in getting there.

I'm sure there are hundreds of tasks that need doing, and granted, we
can't do them all at once, but these are just a few I ran into over the
last three days or so. If I hit them, others may hit a few also.


best regards,

Greg Beam
ki7mt at yahoo.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20140112/b33a0c9c/attachment.pgp>