DocTeam page edit request

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

DocTeam page edit request

mh-dixon
Hi.
Having found two DocumentationTeam "Introduction" pages
I have attempted to tidy the latter in a "playpen"
in the hope that some pruning could be done.
I should be grateful if someone could spare the time to look over my efforts and confirm that I can do a block replacement
has three links to it which I can also amended after which it might be possible to have to deleted.
Thanks in advance, Martin

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

RE: DocTeam page edit request

Doug Smythies

Hi Martin,

 

Looks O.K. to me.

There a couple of formatting issues (bullet points), and a dead link (UbuntuBugControl), that might fix themselves after you do the block replacement.

 

… Doug

 

From: [hidden email] [mailto:[hidden email]] On Behalf Of MARTIN DIXON
Sent: October-29-2013 01:23
To: [hidden email]
Subject: DocTeam page edit request

 

Hi.

Having found two DocumentationTeam "Introduction" pages

I have attempted to tidy the latter in a "playpen"

in the hope that some pruning could be done.

I should be grateful if someone could spare the time to look over my efforts and confirm that I can do a block replacement

has three links to it which I can also amended after which it might be possible to have to deleted.

Thanks in advance, Martin


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

Re: DocTeam page edit request

Little Girl
In reply to this post by mh-dixon
Hey there,

MARTIN DIXON wrote:

> Having found two DocumentationTeam "Introduction" pages
> https://wiki.ubuntu.com/DocumentationTeam/Organization  and
> https://wiki.ubuntu.com/DocumentationTeam I have attempted to tidy
> the latter in a "playpen"
> https://help.ubuntu.com/community/wiki.Ubuntu.com/mh-dixon/sandbox 
> in the hope that some pruning could be done.
> I should be grateful if someone could spare the time to look over
> my efforts and confirm that I can do a block replacement

I like yours much better. Two suggestions, though:

- Rename the Administration heading to Wiki Administration.
- Add a bullet point to the (renamed, if you agreed with me above)
  Wiki Administration section letting users know they should read the
  WikiGuide page here:

https://help.ubuntu.com/community/WikiGuide

Other than that, I'd say it's more succinct and provides a more
"comfortable" reading experience. (:

--
Little Girl

There is no spoon.

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

Re: DocTeam page edit request

mh-dixon
In reply to this post by Doug Smythies
Hi Doug.  Thanks for the blessing and checks. 

The dead link you mentioned is an interesting one as it does not appear as a link in the code, but is "manufactured" in its origional context.  If you could enlarge on the
There are however a couple of oddities revealed in -
"is comfortable working with Bazaar, Launchpad, and either Mallard for the Ubuntu User Guide or DocBook"
where Mallard and DocBook are links Bazaar and Launchpad are not. 
Neither are they when previously mentioned, which raises the general question as to which of all the references in the whole document should be linked in the first place? 

I had expected to find bullets mentioned in the Style Guide but could not. StyleGuide 3. Document Structure is a TODO blank page. 
To explain I replaced numbering with * to avoid conflict with the Contents block.
So I should be grateful if you could enlarge on your concern on this point "There a couple of formatting issues (bullet points)".

Best wishes, Martin

On 29/10/13 14:15, Doug Smythies wrote:

Hi Martin,

 

Looks O.K. to me.

There a couple of formatting issues (bullet points), and a dead link (UbuntuBugControl), that might fix themselves after you do the block replacement.

 

… Doug

 

From: [hidden email] [[hidden email]] On Behalf Of MARTIN DIXON
Sent: October-29-2013 01:23
To: [hidden email]
Subject: DocTeam page edit request

 

Hi.

Having found two DocumentationTeam "Introduction" pages

I have attempted to tidy the latter in a "playpen"

in the hope that some pruning could be done.

I should be grateful if someone could spare the time to look over my efforts and confirm that I can do a block replacement

has three links to it which I can also amended after which it might be possible to have to deleted.

Thanks in advance, Martin



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

Re: DocTeam page edit request

Little Girl
Hey there,

Martin Dixon wrote:

> I had expected to find bullets mentioned in the Style Guide but
> could not. StyleGuide 3. Document Structure is a TODO blank page.
> To explain I replaced numbering with * to avoid conflict with the
> Contents block.

This page gives the syntax for the current version of MoinMoin that
the Ubuntu wiki uses:

https://help.ubuntu.com/community/WikiGuide/Formatting

Those asterisks will be converted to bullets if you put a space in
front of each one (nested sub-items would get two or more spaces for
each level of indentation).

I didn't look at the raw code of the original page that you are doing
your repairs on, but I wouldn't be surprised to find out that the
broken numbered list items are are missing the space in front of
them, too, and that's why the wiki isn't formatting them correctly. (:

--
Little Girl

There is no spoon.

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

RE: DocTeam page edit request

Doug Smythies
In reply to this post by mh-dixon

On 2013.10.30 09:37 Martin wrote:

> The dead link you mentioned is an interesting one as it does not
> appear as a link in the code, but is "manufactured" in
> its original context. 

Yes, that is the exact thing I was referring to as
"demented" in our off-list e-mails and in the
comment for my most recent edit for the page you are trying
to replace.

I absolutely hate the auto insertion of hyperlinks that
the wiki sometimes does. If I want a link, I'll put one in.
There is a way to force it not to add a link, but I forget
how at the moment.

> I had expected to find bullets mentioned in the Style Guide
> but could not. StyleGuide 3.
> To explain I replaced numbering with * to avoid conflict
> with the Contents block.
> So I should be grateful if you could enlarge on your concern
> on this point "There a couple of formatting issues (bullet points)".

LittleGirl covered it in the other branch of this thread.
(yesterday, I did look at the code and thought there was
one case of a set of "space *", but I see that I am mistaken).

... Doug



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

Re: DocTeam page edit request

Little Girl
Hey there,

Doug Smythies wrote:

> I absolutely hate the auto insertion of hyperlinks that
> the wiki sometimes does. If I want a link, I'll put one in.
> There is a way to force it not to add a link, but I forget
> how at the moment.

You can either put an exclamation mark right in front of the
CamelCase word or insert 6 apostrophes between the separate sections.
Examples:

!TwoTwo
!ThreeThreeThree
!FourFourFourFour

Two''''''Two
Three''''''Three''''''Three
Four''''''Four''''''Four''''''Four

All of these will sneak past MoinMoin as non-links. (:

--
Little Girl

There is no spoon.

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

Re: DocTeam page edit request

Elizabeth Krumbach
On Wed, Oct 30, 2013 at 11:50 AM, Little Girl <[hidden email]> wrote:

> You can either put an exclamation mark right in front of the
> CamelCase word or insert 6 apostrophes between the separate sections.
> Examples:
>
> !TwoTwo
> !ThreeThreeThree
> !FourFourFourFour
>
> Two''''''Two
> Three''''''Three''''''Three
> Four''''''Four''''''Four''''''Four
>
> All of these will sneak past MoinMoin as non-links. (:

Backticks work too :)

Two`Two
Three`Three`Three

--
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: DocTeam page edit request

mh-dixon
In reply to this post by mh-dixon
Hi Doug and Little Girl.

I am indebted to you both for more valuable lessons and will sleep on the action until tomorrow.
When I tried to do bullets initially I got so many different combinations that I decided this must be right - ah well another lesson learnt.

I could find no reaction to this bit however -

Intro -
There are however a couple of oddities revealed in -
"is comfortable working with Bazaar, Launchpad, and either Mallard for the Ubuntu User Guide or DocBook"
where Mallard and DocBook are links Bazaar and Launchpad are not.  Neither are they when previously mentioned,

Question -
Which raises the general question as to which of all the references in the whole document should be words (Mallard) or links (Mallard) in the first place?

Any lessons on that?
Regards, Martin

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

Re: DocTeam page edit request

Little Girl
In reply to this post by Elizabeth Krumbach
Hey there,

Elizabeth Krumbach Joseph wrote:

> Little Girl wrote:
> > !TwoTwo
> > !ThreeThreeThree
> > !FourFourFourFour
> >
> > Two''''''Two
> > Three''''''Three''''''Three
> > Four''''''Four''''''Four''''''Four
> >
> > All of these will sneak past MoinMoin as non-links. (:
 
> Backticks work too :)
>
> Two`Two
> Three`Three`Three

Oh, nice! (:

--
Little Girl

There is no spoon.

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

Fwd: DocTeam page edit request

mh-dixon
In reply to this post by mh-dixon
Hi.

Following my original "warning" repeated below, I have (with the very helpful assistance of others) made some changes to
https://wiki.ubuntu.com/DocumentationTeam.

I have now replaced the origional DocumantationTeam page with my edit
and preserved the origional version in https://help.ubuntu.com/community/wiki.Ubuntu.com/mh-dixon2/sandbox

Please would those interested comment on the following suggestions -

Amend the links in

    CategoryDocumentation
    Glossary
    WikiGuide/DeletingAndRenaming

from - https://help.ubuntu.com/community/DocumentationTeam

to - https://wiki.ubuntu.com/DocumentationTeam

and delete the former (community/DocumentationTeam)

If necessary amend any dependent Organisation structure and delete

https://wiki.ubuntu.com/DocumentationTeam/Organization

whilst I may be in a position to amend the links I believe the task of deletions will have to be the responsibility of others.

Regards, Martin.




-------- Original Message --------
Subject: DocTeam page edit request
Date: Tue, 29 Oct 2013 08:22:56 +0000 (GMT)
From: MARTIN DIXON [hidden email]
Reply-To: MARTIN DIXON [hidden email]
To: [hidden email] [hidden email]


Hi.
Having found two DocumentationTeam "Introduction" pages
I have attempted to tidy the latter in a "playpen"
in the hope that some pruning could be done.
I should be grateful if someone could spare the time to look over my efforts and confirm that I can do a block replacement
has three links to it which I can also amended after which it might be possible to have to deleted.
Thanks in advance, Martin



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

Attached Message Part (115 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Fwd: DocTeam page edit request

mh-dixon
Hi.  Regret my failure to explain the update on the Wiki page edit record.

The reference - If necessary amend any dependent Organisation structure
referred to the structure shown on - https://wiki.ubuntu.com/DocumentationTeam/Organization?action=LocalSiteMap
the creation of which I am unaware so cannot comment on dependent changes required.

Advice welcome.  Martin

On 02/11/13 08:41, Martin Dixon wrote:
Hi.

Following my original "warning" repeated below, I have (with the very helpful assistance of others) made some changes to
https://wiki.ubuntu.com/DocumentationTeam.

I have now replaced the origional DocumantationTeam page with my edit
and preserved the origional version in https://help.ubuntu.com/community/wiki.Ubuntu.com/mh-dixon2/sandbox

Please would those interested comment on the following suggestions -

Amend the links in

    CategoryDocumentation
    Glossary
    WikiGuide/DeletingAndRenaming

from - https://help.ubuntu.com/community/DocumentationTeam

to - https://wiki.ubuntu.com/DocumentationTeam

and delete the former (community/DocumentationTeam)

If necessary amend any dependent Organisation structure and delete

https://wiki.ubuntu.com/DocumentationTeam/Organization

whilst I may be in a position to amend the links I believe the task of deletions will have to be the responsibility of others.

Regards, Martin.




-------- Original Message --------
Subject: DocTeam page edit request
Date: Tue, 29 Oct 2013 08:22:56 +0000 (GMT)
From: MARTIN DIXON [hidden email]
Reply-To: MARTIN DIXON [hidden email]
To: [hidden email] [hidden email]


Hi.
Having found two DocumentationTeam "Introduction" pages
I have attempted to tidy the latter in a "playpen"
in the hope that some pruning could be done.
I should be grateful if someone could spare the time to look over my efforts and confirm that I can do a block replacement
has three links to it which I can also amended after which it might be possible to have to deleted.
Thanks in advance, Martin






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

Re: DocTeam page edit request

Little Girl
In reply to this post by mh-dixon
Hey there,

Martin Dixon wrote:

> I could find no reaction to this bit however -
 

> Intro -
> There are however a couple of oddities revealed in -
> "is comfortable working with Bazaar, Launchpad, and either Mallard
> <http://projectmallard.org/index.html> for the Ubuntu User Guide or
> DocBook" <https://help.ubuntu.com/community/DocBook>
> where Mallard and DocBook are links Bazaar and Launchpad are not.
> Neither are they when previously mentioned,
>
> Question -
> Which raises the general question as to which of all the references
> in the whole document should be words (Mallard) or links (Mallard)
> <http://projectmallard.org/index.html> in the first place?
>
> Any lessons on that?

That's a good question, and a weighted one, at that! I took a look at
both below. Feel free to add to, edit, or remove any of my benefits
and drawbacks. (:

--------------------

EVERY LOCATION IS A LINK

Benefits:
- More user-friendly since additional information is always a click
  away no matter where a user is in a page.
- You'll always be able to click to visit the location no matter
  where the reference is in a page.

Drawbacks:
- It might give a cluttered or "busy" look to pages, making them
  difficult to read.
- It might make pages difficult to maintain [see related aside
  below] since you'd have to edit all the links manually if they
  change. The search and replace feature of most applications
  nowadays would simplify this, though.

--------------------

THE FIRST LOCATION ON A PAGE IS A LINK AND ALL THE REST ARE PLAIN TEXT

Benefits:
- Pages will be less cluttered and possibly easier to read.
- Less maintenance if links change.

Drawbacks:
- Less user-friendly on pages that are long or divided into
  sub-sections, where a user might not see the link at the top of the
  page or know to go find it.
- We are creatures of habit, and if we usually don't make location
  references into links, it might be hard to remember to make the
  first reference into a link.


[related aside]
I can't help but put in a plug for the simple elegance of DocBook,
where you define a link in one place and then repeatedly call it with
specific syntax elsewhere. If the link changes, you only need to edit
it in the one place, which automatically updates all the rest.

--------------------

--
Little Girl

There is no spoon.

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

Re: DocTeam page edit request

Little Girl
In reply to this post by mh-dixon
Hey there,

Martin Dixon wrote:

> Following my original "warning" repeated below, I have (with the
> very helpful assistance of others) made some changes to
> https://wiki.ubuntu.com/DocumentationTeam.

This looks good (including all its links), but you might want to do a
search for "this" (case insensitive) and do away with some of them
because it's peppered pretty heavily throughout the page.

> Please would those interested comment on the following suggestions -

[SNIP]

The https://help.ubuntu.com/community/DocumentationTeam page you
mention possibly deleting is redirecting to
https://wiki.ubuntu.com/DocumentationTeam automatically, so I assume
the wiki team is leaving it in place to prevent broken links and give
people a chance to update their bookmarks.

I'm going to be useless at figuring out any of the rest of the links I
snipped because you seem to have discovered a third wiki, so now
there are these:

https://help.ubuntu.com/

https://help.ubuntu.com/community

https://wiki.ubuntu.com/

I'm so confused. What's even worse is that this has probably already
been discussed, but I can never keep all these wikis straight in my
head or remember which is for what. Ack! (:

--
Little Girl

There is no spoon.

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

Re: DocTeam page edit request

Svetlana Belkin
In reply to this post by Little Girl
On 11/02/2013 11:39 AM, Little Girl wrote:
> - We are creatures of habit, and if we usually don't make location
>   references into links, it might be hard to remember to make the
>   first reference into a link.

Would a [1] work by the text that the link is referring to, like how
wikipedia does it?

Svetlana Belkin
--
https://wiki.ubuntu.com/belkinsa

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

Re: DocTeam page edit request

mh-dixon
In reply to this post by Little Girl
Martin Dixon wrote <snip>
I have .......made some changes to
https://wiki.ubuntu.com/DocumentationTeam. <snip>
 

On 02/11/13 15:56, Little Girl wrote:

> This looks good (including all its links), but you might want to do a
> search for "this" (case insensitive) and do away with some of them
> because it's peppered pretty heavily throughout the page.
>
> [SNIP]
>
I must have been very distracted to have left "this" like that.
Repetition usually makes me very sore!
It should not take too much to sort out.

Re the heap of Wikis that is really part of the whole Wiki challenge, I
just thought I might get away with that one as a balance to creating two
sandboxes to play in!
I await further reaction and enlightenment on that front.

More on links soon.

Martin

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

Re: DocTeam page edit request

mh-dixon
In reply to this post by Svetlana Belkin
+1  for SB's suggestion, but Doug might have a comment on forced Wiki links which I will have to check again.

My initial reaction to LG's considered analysis is that a general rule is easy to follow for the writer of the page, but may not always be appropriate. For example if you write an Introduction the reader will be encouraged to stay with it if there are no links. Equally if you are defining a role there is a case for stating the activity and then defining the requirements for that role. Further question does this discussion relate to the wider question of “to whom is the page directed”?. A lay or Newbie reader might be interested in the different Documentation activities in a general way without any requirement to specifically address the detail of how each activity addresses the actual job. However, once one has moved on there is a very real need to ensure that the reader has as much information available easily so that one (he/she!) can decide for one'self which links to follow and when.
Martin

On 02/11/13 16:03, Svetlana Belkin wrote:
On 11/02/2013 11:39 AM, Little Girl wrote:
- We are creatures of habit, and if we usually don't make location
  references into links, it might be hard to remember to make the
  first reference into a link.
Would a [1] work by the text that the link is referring to, like how
wikipedia does it?

Svetlana Belkin


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

Re: DocTeam page edit request

mh-dixon
In reply to this post by Svetlana Belkin
Hi
So that we have a "live" target to challenge I have made a first stab at
implementing Svetlana's suggestion - it will need "tarting up"!
https://help.ubuntu.com/community/wiki.Ubuntu.com/mh-dixon/sandbox
Best wishes, Martin

On 02/11/13 16:03, Svetlana Belkin wrote:
> On 11/02/2013 11:39 AM, Little Girl wrote:
>> - We are creatures of habit, and if we usually don't make location
>>   references into links, it might be hard to remember to make the
>>   first reference into a link.
> Would a [1] work by the text that the link is referring to, like how
> wikipedia does it?
>
> Svetlana Belkin


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

RE: DocTeam page edit request

Doug Smythies
Hi Martin.

I adamantly do not support this change. It makes no sense to me to remove
the power and convenience of local hyperlinks at the same location as the
referring text.
I apologize for not chiming in earlier (i.e. before you did a bunch of
work), but I the direction of the thread didn't really sink in for me until
I saw your example, just now.

... Doug

-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of Martin Dixon
Sent: November-03-2013 01:10
To: Svetlana Belkin; Little Girl
Cc: Ubuntu Doc
Subject: Re: DocTeam page edit request

Hi
So that we have a "live" target to challenge I have made a first stab at
implementing Svetlana's suggestion - it will need "tarting up"!
https://help.ubuntu.com/community/wiki.Ubuntu.com/mh-dixon/sandbox
Best wishes, Martin

On 02/11/13 16:03, Svetlana Belkin wrote:
> On 11/02/2013 11:39 AM, Little Girl wrote:
>> - We are creatures of habit, and if we usually don't make location
>>   references into links, it might be hard to remember to make the
>>   first reference into a link.
> Would a [1] work by the text that the link is referring to, like how
> wikipedia does it?
>
> Svetlana Belkin


--
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: DocTeam page edit request

mh-dixon
Hi Doug.

That was the whole purpose of my doing the sample in my playpen - so
that others could see clearly what was being suggested.
As I indicated in a previous email I believe this links question is just
a subset of a much larger one and whilst I am very keen on perfection(!)
I am also very well aware that the wiki docs need a lot of work and that
is perhaps more important.  But I consider that is all for much more
experienced minds to decide.
Perhaps I would not have bothered (with the links) if my previous work
had not been deleted overnight and I did not feel the need to have
achieved something more!
Your opinions are always appreciated at this end - thanks for the
reply.  Regards Martin

On 03/11/13 14:32, Doug Smythies wrote:

> Hi Martin.
>
> I adamantly do not support this change. It makes no sense to me to remove
> the power and convenience of local hyperlinks at the same location as the
> referring text.
> I apologize for not chiming in earlier (i.e. before you did a bunch of
> work), but I the direction of the thread didn't really sink in for me until
> I saw your example, just now.
>
> ... Doug
>
> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]] On Behalf Of Martin Dixon
> Sent: November-03-2013 01:10
> To: Svetlana Belkin; Little Girl
> Cc: Ubuntu Doc
> Subject: Re: DocTeam page edit request
>
> Hi
> So that we have a "live" target to challenge I have made a first stab at
> implementing Svetlana's suggestion - it will need "tarting up"!
> https://help.ubuntu.com/community/wiki.Ubuntu.com/mh-dixon/sandbox
> Best wishes, Martin
>
> On 02/11/13 16:03, Svetlana Belkin wrote:
>> On 11/02/2013 11:39 AM, Little Girl wrote:
>>> - We are creatures of habit, and if we usually don't make location
>>>   references into links, it might be hard to remember to make the
>>>   first reference into a link.
>> Would a [1] work by the text that the link is referring to, like how
>> wikipedia does it?
>>
>> Svetlana Belkin
>


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