Re: Desktop help - Unity files Vs. GNOME files

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Desktop help - Unity files Vs. GNOME files

Benjamin Kerensa

So my thoughts are that in the near future it is likely we will see more convergence of Ubuntu's code and UI between Desktop and Mobile.

When this occurs we will need to consider whether merging in GNOME is the best step forward.

Considering UI changes it might make more sense to stop syncing and just become our own upstream since we would have to drastically change GNOME doc.

On Jan 11, 2014 3:23 PM, "Doug Smythies" <[hidden email]> wrote:
>
> Hi,
>
>  
>
> KI7MT ( Greg ) has done some good work for his merge proposal(s).
>
>  
>
> As I also wrote in the MP itself, I think we need to make a conscious decision going forward if we are going to deviate more and more from the GNOME docs or not. Currently, the GNOME help has, as much as is possible, the same look and feel as the Unity help. And as much as possible, the files are inherited from the upstream GNOME help (However, Kevin understands that process much better than I). If we do agree to deviate going forward then maybe we can delete the conditional stuff.
>
>  
>
> Myself, I don’t really care either way, I just want us to think about it. Also, I don’t fully understand the current workflow and possible duplicate effort scenarios. Since Kevin did most, if not all, of the re-syncing work between GNOME upstream files and ours last cycle, he should comment.
>
>  
>
> Attached are screen shots of the help pages for all 3 of: Unity help proposed (leftmost); Unity help the way it is now (middle); GNOME help (rightmost).
>
>  
>
> online-index.png – It is not clear to me that the name “control …” shouldn’t have been left as it was. Notice the addition of license info under “about”, which if it is going to be done, should be done for every file.
>
>  
>
> online-add.png – Looks O.K. to me.
>
>  
>
> online-disable.png – Myself I wouldn’t have deleted the sentence nor added the blue circle with the “i” in it nor deleted the see also “Which …” reference.
>
>  
>
> online-remove.png – Should the added note be suggested for upstream (GNOME)?
>
>  
>
> online-which.png – to be consistent, it need the license stuff. The copyright sign doesn’t make any sense under any licensing for this stuff that I know of (and as was discussed on IRC).
>
>  
>
> online-why.png – Greg did the work and wants to delete the bullet point list, O.K. Why change the yellow rectangle with a pin to a yellow star?
>
>  
>
> online-why-add.png - to be consistent, it need the license stuff. The copyright sign. Should the paragraph changes be suggested for upstream (GNOME)? (note: the middle help menu is more buried on purpose, to be able to read and compare the entire paragraph).
>
>  
>
> … Doug
>
>  


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Desktop help - Unity files Vs. GNOME files

Gunnar Hjalmarsson
On 2014-01-12 00:39, Benjamin Kerensa wrote:
> Considering UI changes it might make more sense to stop syncing and
> just become our own upstream since we would have to drastically
> change GNOME doc.

This time (14.04), at least, I think we should sync when feasible.

> On Jan 11, 2014 3:23 PM, "Doug Smythies" <[hidden email]
> <mailto:[hidden email]>> wrote:
>> I think we need to make a conscious decision going forward if we
>> are going to deviate more and more from the GNOME docs or not.
>> Currently, the GNOME help has, as much as is possible, the same
>> look and feel as the Unity help. And as much as possible, the files
>> are inherited from the upstream GNOME help (However, Kevin
>> understands that process much better than I). If we do agree to
>> deviate going forward then maybe we can delete the conditional
>> stuff.
>>
>> Myself, I don’t really care either way, I just want us to think
>> about it.

I certainly agree we should - after the doc freeze. ;-)

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Desktop help - Unity files Vs. GNOME files

Stephen M. Webb-4
In reply to this post by Benjamin Kerensa
On 01/11/2014 06:39 PM, Benjamin Kerensa wrote:
> So my thoughts are that in the near future it is likely we will see more convergence of Ubuntu's code and UI between
> Desktop and Mobile.

Point of order: not until after 14.04 LTS.

--
Stephen M. Webb  <[hidden email]>

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

[ Dekstop Help ] First Contributions - Lesson Learned

Greg Beam-2
In reply to this post by Benjamin Kerensa
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
[hidden email]


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

signature.asc (501 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [ Dekstop Help ] First Contributions - Lesson Learned

mh-dixon
+1 for all said (I have shied away from further work partly due to finding texts that I could follow) particularly thanks to those listed  and others for past help.
Martin



From: Greg Beam <[hidden email]>
To: Benjamin Kerensa <[hidden email]>; Doug Smythies <[hidden email]>; Little Girl <[hidden email]>; Kevin Godby <[hidden email]>; Ubuntu Docs <[hidden email]>
Sent: Sunday, 12 January 2014, 9:35
Subject: [ Dekstop Help ] First Contributions - Lesson Learned

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
[hidden email]


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: [ Dekstop Help ] First Contributions - Lesson Learned

Stephen M. Webb-4
In reply to this post by Greg Beam-2
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 01/12/2014 04:35 AM, Greg Beam wrote:
>
> - 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.

/self grumbles about too many unmaintained web pages on Ubuntu.com...

> * 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.

The Bazaar terminology is 'branch.'  You can only work on a single branch at a time.  This is identical to other
distributed version control systems, like git.  The difference is that without using Bazaar plugins, each branch is a
separate directory on your filesystem.  Git and Mercurial allow you to work on separate branches in the same directory
by providing a virtual filesystem that can be swapped in and out.

There is good Bazaar documentation on this [1].  Is it not linked from the Wiki page?

> * 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

The only problem with that workflow is that you're trying to subvert Bazaar.  It's better to do this:

 bzr branch lp: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

Why not check out once and copy?  Because in the mean time someone could have checked in changes to lp:ubuntu-docs and
you would be working from a stale branch.  You could even end up overwriting someone else's changes, although Bazaar
is pretty good about preventing that, forcing you to go back and redo everything with a fresh checkout anyway.  Always
start with a fresh checkout.  On busy projects (ones with more than one active developer), I usually merge from
Launchpad again before create a merge proposal in case the branches have diverged.

If you need to reduce bandwidth, you can use --lightweight to not copy history.

[1] http://doc.bazaar.canonical.com/latest/en/user-guide/branching_a_project.html

- --
Stephen M. Webb  <[hidden email]>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.14 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBCAAGBQJS0q2/AAoJEAoP+EW32zQnO3YQAMC6lXgVCQAQZzKdfL4pOU/1
XmJYcID84opKZvkw5LGtSwWpE880X+U6edx61JgbN85se78wfdT63E3snLAp7Idc
p4jAXhIFpE/92wQMXJ2tbW13HJWHaxML6KV4ALN7ditddrDbPQ7j3VnE4yi41gCY
9xveif/HQE/jz7CUBYalkoaIDr/knqwOhScjKoviE5gWFPYOBvYAe8Y8mL2vzbCK
gPygMysDtbYioc7PneggVlzZ1Rdf6ETTssA7EUu91W1tlJb2vJJtdd+mExn5YYEy
HcHwTEdumO/ekFIq6KPI1Eq936yXGwmcbyzVPO4tvKqvSMTxRJ/5yM8EMyaL9OwO
Sg9v4spRYdQosHAUVii90n8e9mM5NQsSBccS6Kvcm8aMD/ajsndpuodNak2TC85/
LIge0s8PHhYtKskSpDpHst5KDlP9w/9DFgMz1SOP8k3a0ARP+1zj4ZQKISq7z90k
lclcQFk4EKOgm9dhSreQQfOD+rdzO/8iUDPbPW3LySgwX5Srg5Q2WdA0efiP7nsx
UMz7wGEUwExhlYywGbF5MD2t241uSgwolD0mdI/CGlBLcTWmIWrWCORksxVWjnIj
/1XR/FjVS4UjakXbQmeElBf0FczWyK8wGn8/m64GI1PIBK2ViMeziBlLSY3EqbJb
8U0UAoKysNQTylyKjFzw
=xBXi
-----END PGP SIGNATURE-----

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: [ Dekstop Help ] First Contributions - Lesson Learned

Doug Smythies
Herein, I am just commenting on something that was left
out from the IRC stuff on this:

On 2014.01.12 06:59 Stephen M. Webb wrote:
On 01/12/2014 04:35 AM, Greg Beam wrote:

> Why not check out once and copy?  Because in the mean time someone
> could have checked in changes to lp:ubuntu-docs and
> you would be working from a stale branch.

Yes, but gnome said to always do a "bzr pull" on your
local "base" directory before the copy step such that
it is always up to date.

> If you need to reduce bandwidth, you can use --lightweight to
> not copy history.

Yes, a very good point.



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: [ Dekstop Help ] First Contributions - Lesson Learned

Doug Smythies
In reply to this post by Greg Beam-2
Greg: Thanks for this e-mail. There is huge value when someone new writes about their learning curve issues. After doing it a few times, one tends to develop workarounds in their brain and it becomes less obvious what is wrong.

Other readers should know that you dug into things so deep and thoroughly that it was difficult to keep up with you on IRC.

On 2014.01.12 01:35 Greg Beam wrote:

> For the experienced dev's, contributors and editors,
> this may be white noise

Just so you know, none of us are all that experienced.
The truly experienced and knowledgeable have left the
project. We are merely trying to carry on.

> where the would be new
> contributor is left saying "this is not
> worth the pain!!".

We are well aware of the "not worth the pain" issue.
Believe me, it is not limited to the "would be new
contributor".

> - Tasks Tab:

Yes, brutally out of date.
I wonder if one of the wiki tag experts (from those e-mails that
I did not pay attention to) could add an indicator.

> - 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.

Yes, most of the content needs to be deleted and the reader pointed to the getting started pages.
For my part of it, sorry. I knew that this page was largely redundant with the new getting started pages, but failed to change it.

> - Checking TAB:

Yes, we should delete its build instructions and point the reader to the build page and the getting started pages, or delete the page entirely.

> * 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.

I consider this to be partly your issue, because you already know so much.
Just use the getting started or BUILB TAB build instructions and don't
even think about using yelp-build directly.

> * We need copyright policies clearly stated with examples.

Hence the other email thread. Lets figure it out.

> * We need Unity specific .stub files and the method to generate pages.

Huh? Don't understand.

> * We need guidance on Gnome to Unity separation, what, how much, and by
> when, the old W3 thing (Who, What & When).

Hence the other email thread. Lets figure it out.



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: Desktop help - Unity files Vs. GNOME files

Doug Smythies
In reply to this post by Benjamin Kerensa

I see that Benjamin copied the list on his reply. I had not intended this e-mail for the list, at least not yet. I wasn’t trying to specifically exclude the list, but I knew that I couldn’t include attachments of the size that I did.

And to clarify, I am not talking about the future after 14.04, I am talking about now, and the precedence that will be established by two merge proposals, one that has been already been merged and one that is pending.

Anyway, if anyone wants to look at the referred to screen shot files, then please see (in code to prevent automated address harvesters from getting the URL):

 

Double you double you double you dot smythies dot com forward slash ~doug forward slash temp_U_doc   (<- that is a capital U)

 

… Doug

 

From: [hidden email] [mailto:[hidden email]] On Behalf Of Benjamin Kerensa
Sent: January-11-2014 15:40
To: Doug Smythies
Cc: KI7MT; Little Girl; Kevin Godby; [hidden email]
Subject: Re: Desktop help - Unity files Vs. GNOME files

 

So my thoughts are that in the near future it is likely we will see more convergence of Ubuntu's code and UI between Desktop and Mobile.

When this occurs we will need to consider whether merging in GNOME is the best step forward.

Considering UI changes it might make more sense to stop syncing and just become our own upstream since we would have to drastically change GNOME doc.

On Jan 11, 2014 3:23 PM, "Doug Smythies" <[hidden email]> wrote:


>
> Hi,
> KI7MT ( Greg ) has done some good work for his merge proposal(s).
> As I also wrote in the MP itself, I think we need to make a conscious decision going forward if we are going to deviate more and more from the GNOME docs or not. Currently, the GNOME help has, as much as is possible, the same look and feel as the Unity help. And as much as possible, the files are inherited from the upstream GNOME help (However, Kevin understands that process much better than I). If we do agree to deviate going forward then maybe we can delete the conditional stuff.
> Myself, I don’t really care either way, I just want us to think about it. Also, I don’t fully understand the current workflow and possible duplicate effort scenarios. Since Kevin did most, if not all, of the re-syncing work between GNOME upstream files and ours last cycle, he should comment.
> Attached are screen shots of the help pages for all 3 of: Unity help proposed (leftmost); Unity help the way it is now (middle); GNOME help (rightmost).
> online-index.png – It is not clear to me that the name “control …” shouldn’t have been left as it was. Notice the addition of license info under “about”, which if it is going to be done, should be done for every file.
> online-add.png – Looks O.K. to me.
> online-disable.png – Myself I wouldn’t have deleted the sentence nor added the blue circle with the “i” in it nor deleted the see also “Which …” reference.
> online-remove.png – Should the added note be suggested for upstream (GNOME)?
> online-which.png – to be consistent, it need the license stuff. The copyright sign doesn’t make any sense under any licensing for this stuff that I know of (and as was discussed on IRC).
> online-why.png – Greg did the work and wants to delete the bullet point list, O.K. Why change the yellow rectangle with a pin to a yellow star?
> online-why-add.png - to be consistent, it need the license stuff. The copyright sign. Should the paragraph changes be suggested for upstream (GNOME)? (note: the middle help menu is more buried on purpose, to be able to read and compare the entire paragraph).
> … Doug


--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: [ Dekstop Help ] First Contributions - Lesson Learned

Greg Beam-2
In reply to this post by Doug Smythies
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Doug,

Thanks for your feedback, see comments below:

On 01/12/2014 09:49 AM, Doug Smythies wrote:

> Greg: Thanks for this e-mail. There is huge value when someone new
> writes about their learning curve issues. After doing it a few
> times, one tends to develop workarounds in their brain and it
> becomes less obvious what is wrong.
>
> Other readers should know that you dug into things so deep and
> thoroughly that it was difficult to keep up with you on IRC.
>
> On 2014.01.12 01:35 Greg Beam wrote:
>
>> For the experienced dev's, contributors and editors, this may be
>> white noise
>
> Just so you know, none of us are all that experienced. The truly
> experienced and knowledgeable have left the project. We are merely
> trying to carry on.
>
>> where the would be new contributor is left saying "this is not
>> worth the pain!!".
>
> We are well aware of the "not worth the pain" issue. Believe me, it
> is not limited to the "would be new contributor".
>
>> - Tasks Tab:
>
> Yes, brutally out of date. I wonder if one of the wiki tag experts
> (from those e-mails that I did not pay attention to) could add an
> indicator.

- -----
I think most of us in the group can add the Tags, just edit the page
and add the tag to the top.

<<Include(Tag/NeedsUpdating)>>

Tag info can be found here: https://help.ubuntu.com/community/Tag

I built a Moin Moin Wiki for local code testing, but I am not to the
point where I would take on a large page reconstruction.
- -----

>
>> - 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.
>
> Yes, most of the content needs to be deleted and the reader pointed
> to the getting started pages. For my part of it, sorry. I knew that
> this page was largely redundant with the new getting started pages,
> but failed to change it.
>
>> - Checking TAB:
>
> Yes, we should delete its build instructions and point the reader
> to the build page and the getting started pages, or delete the page
> entirely.
>
>> * 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.

> I consider this to be partly your issue, because you already know
> so much. Just use the getting started or BUILB TAB build
> instructions and don't even think about using yelp-build directly.

- -----
Yes, one of my many blunders, but it is a nice tool. I wish we could
incorporate its use somehow.
- -----

>> * We need copyright policies clearly stated with examples.
>
> Hence the other email thread. Lets figure it out.
>
>> * We need Unity specific .stub files and the method to generate
>> pages.
>
> Huh? Don't understand.

- -----
Even though we are not using yelp-build, we could still use yelp-new
to generate standard pages, index, guides, tasks etc. Can be the
normal .page or .stub for testing or whatever.

Link: https://wiki.gnome.org/Apps/Yelp/Tools/yelp-new

This could help us maintain some level of consistency, at least at
initial page generation, plus it saves coding time.

In ./ubuntu-docs do a quick: grep -R '.stub'

You'll see the files and <status="stub">
- -----

>> * We need guidance on Gnome to Unity separation, what, how much,
>> and by when, the old W3 thing (Who, What & When).
>
> Hence the other email thread. Lets figure it out.
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.15 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJS0tYDAAoJEAmfcyeKlj0x3NEIALIBEIA28uv7+fnWFabqyWu5
0b0wZjlJF8L2CmJDnYtKo5gsXHSuehVOpcL0pEOnZfiBzpEzB1ljbVKIk1V6ajrU
CCHyOypuRnSBdjeWlLGmFeZYbQmbpZZuu6UtZd6zt5QH/ClJuSSy9daerp9I++k4
5IsPaxX+N2iREHkcCY2kFP6M82aFE0kmNGVTiPppqd6LqKc+QE0/0M7n579VgEZ5
kj/nt7wrmBUDB0cSf6h1ECMvhqVsaMr8HAGM6b8dgbs1tRdfd1c0ASMGfW3MvWY7
ubI/W8fVn/Pt6VqqjucXUaZtpcWk52KBqtQQRioeucbrsyAUnh8sb0XJkY04QJ4=
=PdTm
-----END PGP SIGNATURE-----

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: [ Dekstop Help ] First Contributions - Lesson Learned

Greg Beam-2
In reply to this post by Stephen M. Webb-4
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Stephen,

Thanks for your comments. Pse see my comments below.

On 01/12/2014 07:59 AM, Stephen M. Webb wrote:

> On 01/12/2014 04:35 AM, Greg Beam wrote:
>
>> - 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.
>
> /self grumbles about too many unmaintained web pages on
> Ubuntu.com...
>
>> * 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.
>
> The Bazaar terminology is 'branch.'  You can only work on a single
> branch at a time.  This is identical to other distributed version
> control systems, like git.  The difference is that without using
> Bazaar plugins, each branch is a separate directory on your
> filesystem.  Git and Mercurial allow you to work on separate
> branches in the same directory by providing a virtual filesystem
> that can be swapped in and out.

- -----
Yes, I need to learn allot more about bzr for sure. I suppose my main
point was, we should structure the Wiki in such a way that it explains
how to set up and maintain things for use with ubuntu-docs
specifically, as each project has it's own why of doing things. Maybe
examples on the Wiki for branching, merging and working multiple
issues would be helpful. A visual work-flow would be useful too.
- -----

>
> There is good Bazaar documentation on this [1].  Is it not linked
> from the Wiki page?
>
>> * 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
>
> The only problem with that workflow is that you're trying to
> subvert Bazaar.  It's better to do this:
>
> bzr branch lp: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

- -----
I was using that method initially. I followed the Wiki and created a
shared ubuntu-bzr repo. When I added commits to the second branch
ubuntu-docs-lp6789-fix then further pushed the MP, it caused problems.

knome also told me to do bzr pull from time to time an make sure
ubuntu-docs-base was up to date before cp -R. I forgot to add that part.
- -----

> Why not check out once and copy?  Because in the mean time someone
> could have checked in changes to lp:ubuntu-docs and you would be
> working from a stale branch.  You could even end up overwriting
> someone else's changes, although Bazaar is pretty good about
> preventing that, forcing you to go back and redo everything with a
> fresh checkout anyway.  Always start with a fresh checkout.  On
> busy projects (ones with more than one active developer), I usually
> merge from Launchpad again before create a merge proposal in case
> the branches have diverged.

- -----
Yes, I check bzr update regularly, I just did not state it.
- -----

>
> If you need to reduce bandwidth, you can use --lightweight to not
> copy history.

- ----
They may be an option as well, I need to read more on that.
- ----

> [1]
> http://doc.bazaar.canonical.com/latest/en/user-guide/branching_a_project.html
>
>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.15 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJS0tsTAAoJEAmfcyeKlj0xuZgIAO2QYXPFkErZ/3RytDXk/WRT
m30eFQWwZmyddD2tpeniZB+SUxX4koJ7/eN39oNa/zYX07oQusMS/rdjsl/wNagt
oZdpDPrXtuVH3pNdggaDAZhsSrnn5AvttfLB+LJLT3ubDrU38Ih03wyyd/rMbhs8
8yL8E32MiWNs0jgMkL7a4+oFf6eutqJdqB14PAi/ptfgfQLDviHiGuYngSFagnXY
VEh6aNz8gC6P9+UXW/Gk1KeDzgt9Uxx7P8HYsb9lx1W76gg5FMccAbTQQZThJV7m
xYoN+PP7yX/H/YP1AG3kTIHsvVk6ccoS5OVok1a5vCkZPoo6jxJM6BNcoaEpO1g=
=Oezo
-----END PGP SIGNATURE-----

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Desktop help - Unity files Vs. GNOME files

Greg Beam-2
In reply to this post by Doug Smythies
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Doug,

So to move the MP-Update forward or if deemed necessary, revert to
324, what exactly is needed here? I'd like to get this resolved one
way or another so we can all move onto other things.

Greg
[hidden email]


On 01/12/2014 10:07 AM, Doug Smythies wrote:

> I see that Benjamin copied the list on his reply. I had not
> intended this e-mail for the list, at least not yet. I wasn't
> trying to specifically exclude the list, but I knew that I couldn't
> include attachments of the size that I did.
>
> And to clarify, I am not talking about the future after 14.04, I am
> talking about now, and the precedence that will be established by
> two merge proposals, one that has been already been merged and one
> that is pending.
>
> Anyway, if anyone wants to look at the referred to screen shot
> files, then please see (in code to prevent automated address
> harvesters from getting the URL):
>
>
>
> Double you double you double you dot smythies dot com forward slash
> ~doug forward slash temp_U_doc   (<- that is a capital U)
>
>
>
> . Doug
>
>
>
> From: [hidden email] [mailto:[hidden email]] On Behalf Of
> Benjamin Kerensa Sent: January-11-2014 15:40 To: Doug Smythies Cc:
> KI7MT; Little Girl; Kevin Godby; [hidden email]
> Subject: Re: Desktop help - Unity files Vs. GNOME files
>
>
>
> So my thoughts are that in the near future it is likely we will see
> more convergence of Ubuntu's code and UI between Desktop and
> Mobile.
>
> When this occurs we will need to consider whether merging in GNOME
> is the best step forward.
>
> Considering UI changes it might make more sense to stop syncing and
> just become our own upstream since we would have to drastically
> change GNOME doc.
>
> On Jan 11, 2014 3:23 PM, "Doug Smythies" <[hidden email]>
> wrote:
>>
>> Hi, KI7MT ( Greg ) has done some good work for his merge
>> proposal(s). As I also wrote in the MP itself, I think we need to
>> make a conscious
> decision going forward if we are going to deviate more and more
> from the GNOME docs or not. Currently, the GNOME help has, as much
> as is possible, the same look and feel as the Unity help. And as
> much as possible, the files are inherited from the upstream GNOME
> help (However, Kevin understands that process much better than I).
> If we do agree to deviate going forward then maybe we can delete
> the conditional stuff.
>> Myself, I don't really care either way, I just want us to think
>> about it.
> Also, I don't fully understand the current workflow and possible
> duplicate effort scenarios. Since Kevin did most, if not all, of
> the re-syncing work between GNOME upstream files and ours last
> cycle, he should comment.
>> Attached are screen shots of the help pages for all 3 of: Unity
>> help
> proposed (leftmost); Unity help the way it is now (middle); GNOME
> help (rightmost).
>> online-index.png - It is not clear to me that the name "control
>> ."
> shouldn't have been left as it was. Notice the addition of license
> info under "about", which if it is going to be done, should be done
> for every file.
>> online-add.png - Looks O.K. to me. online-disable.png - Myself I
>> wouldn't have deleted the sentence nor added
> the blue circle with the "i" in it nor deleted the see also "Which
> ." reference.
>> online-remove.png - Should the added note be suggested for
>> upstream
> (GNOME)?
>> online-which.png - to be consistent, it need the license stuff.
>> The
> copyright sign doesn't make any sense under any licensing for this
> stuff that I know of (and as was discussed on IRC).
>> online-why.png - Greg did the work and wants to delete the bullet
>> point
> list, O.K. Why change the yellow rectangle with a pin to a yellow
> star?
>> online-why-add.png - to be consistent, it need the license stuff.
>> The
> copyright sign. Should the paragraph changes be suggested for
> upstream (GNOME)? (note: the middle help menu is more buried on
> purpose, to be able to read and compare the entire paragraph).
>> . Doug
>
>
>
>
>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.15 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJS0uNVAAoJEAmfcyeKlj0xOn8H/Aql4AcbJV5m5NM85TRAZvAi
8GoAn3B8kzZisIrquefyEQ6cDLrslsZVxoJSsxnoUwvOdpC8+CUbbYIHSKwAKEiG
xeuSNmiReaDFiGAT8dAHpzXvX0p4aQ2t7XibJDcYY1nmMekDNsj1ek/aAj83e3+T
4ewX/5xsfPu4DqEhZJldq6pNaqV3ryFK+yIgE5T69YcdNdQdxYDlIqIS++zNazoa
+t7bqYBzGvlos0ydSqtd6iNm3Gf9LC3D/KyqY0XE1/s6vcDOGWTc+gQPPIc36h6H
fq3HWLStsXSx3D3QDvplV7wPNb8uwaEuIRn4sDMbqqegTAdnhp3MT0P909iQ6R0=
=2ATw
-----END PGP SIGNATURE-----

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: Desktop help - Unity files Vs. GNOME files

Gunnar Hjalmarsson
On 2014-01-12 19:47, Greg Beam wrote:
> Hi Doug,
>
> So to move the MP-Update forward or if deemed necessary, revert to
> 324, what exactly is needed here?

I'm not Doug, but... I accidentally noticed an issue and addressed it on
the MP (after merging). For now I'd suggest that somebody just commits
the old version of legal.xml, together with possible other things that
I'm not aware about, as a new revision. After all, we need to move
forward, and reverting commits to lp:ubuntu-docs should be reserved for
exceptional cases IMO.

--
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

Re: [ Dekstop Help ] First Contributions - Lesson Learned

Elizabeth K. Joseph
In reply to this post by Greg Beam-2
On Sun, Jan 12, 2014 at 1:35 AM, Greg Beam <[hidden email]> wrote:
> 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.

Huge thanks for taking the time to write this up!

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

I think part of our problem with the wiki is that it's not intended to
just cover the Ubuntu Desktop help, which is in Mallard. The
xubuntu-docs and serverguide at least are still on DocBook. While we
can share bzr workflow documentation, there will always be a split
between projects using Mallard and those using Docbook, and now the
server folks are talking about switching to RST.

So I agree that this page should be overhauled, but not by deleting
DocBook references, probably by writing a more clear description of
which projects use what (I can try to take a stab at this over the
weekend).

--
Elizabeth Krumbach Joseph || Lyz || pleia2
http://www.princessleia.com

--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
Reply | Threaded
Open this post in threaded view
|

RE: [ Dekstop Help ] First Contributions - Lesson Learned

Doug Smythies
In reply to this post by Greg Beam-2
Some work has been done on some of the references
given.

I make no claim that they are now great and wonderful.
I only make the claim that they are much less wrong than
before.

Please review and continue to make changes.

On 2014.01.12 01:35 Greg Beam wrote:

> 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.

Has been re-worked, basically now pointing to the current task list
areas for Desktop help and Serverguide. Xubuntu doesn't have such a list.

> - 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. ...

Has been re-worked.

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

Has been re-worked.

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

Has been re-worked.

> - Submitting TAB:
> -----------------

Has been re-worked.

- Building TAB:

Was not mentioned, but I have been updating that page as
required for a couple of cycles now.



--
ubuntu-doc mailing list
[hidden email]
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc