Getting involved in the docs team
Tom Davies
tomdavies04 at yahoo.co.uk
Tue Mar 26 10:47:00 UTC 2013
Hi :)
I normally hate reading documentation. The only way i can read it is if i am proof-reading or editing to de-geekify or help where someone is clearly not a native English (or comes from a council housing estate or is a wanna-be gangsta or is a geordie or something) or to help edit out bits that are clearly spam. I had a brief go qwith the documentation about how to write documentation but gave up really fast because it didn't seem related to what i was finding on the wiki-pages themselves.
The only way i could get into it was trial and practice. The mark-up language used on some pages seems to be different from that used on other pages and there even seems to be some inconsistencies within some pages. Eventually i learned to use the "Preview" option to check how wrong my efforts were.
All the different mark-ups seem very similar and have huge overlaps so i'm not sure it helps to focus on just one. Also some are very pedantic about needing a space after
===
on a line and empty line before and/or after but others seem to not care. Similarly with bullet-points. Some pages seem to allow a few spaces at the start of the line and translate that into indents. Other pages don't seem to allow it.
So, my tactic was to
1. try a whole bunch of things out
2. if some things didn't work out then try doing that thing 3 different ways in preview
3. if none of those worked then have a quick squiz at the rest of the page and copy&paste an example that did work and/or have a quick squiz at other pages and see if i could copy&paste from them
4. once the right way is found for that page (in preview) then change all the rest of my edits to conform to that
5. check that it still looks right after publishing
Since that was such a Pita (but only sometimes) i found myself trying to get pages internally consistent so that if the same thing was done in 3 different ways then i would pick on the one that seemed to be being used most widely in other pages and see if the page could work using that 1 way throughout.
Another thing i often did was to copy&paste the few lines at the top that put a "Table of Contents" at the top of the page. Many pages grow organically over the years and obviously started off very small. Unfortunately doing the ToCs all the same width doesn't work. Either it messes-up the text layout or the ToC looks dumb. So a bit of fiddling around with that % figure can have a hugely positive result for the look of the individual page. There is a good argument for having all the ToCs the same width but it would make most pages look very scrappy.
Since there are so many 'new' people taking an interest since yday please can i request that titles and sub-headings are written in either Title Case or Camel Case NOT all lower case and NOT all uppers either. All upper-case looks rude. Also pleeease keep titles and sub headings (and sub-sub-sub-headings) short.
Taking a stupid example from elsewhere i have seen this sort of thing quite a lot:
In a folder called
"Star Trek"
a sub-folder
"Star Trek - The Next Generation"
"Star Trek - The Next Generation - Season One"
"Star Trek - The Next Generation - Season One - Episode One blah blah"
which makes the pathname incomprehensible and long ...
"Star%20Trek/Star%20Trek%20-%20Th%20Next%20Generation/Star%20Trek%20-%20The%20Next%20Gneration%20%20Season%20One/Star%20Trek%20-%20The%20Next%20Generation%20-%20Season One%20-%20Epsode%20One%20blah%20blah"
Plus it's difficult to spot the 4 errors in there especially if you didn't know how many errors.
So, it's better to use CamelCase for page names but spaces between words, to make it into Title Case, is ok for titles and sub-headings within a page.
Unfortunately changing pages names or even titles and sub-sub headings in pages may well destroy links from other pages or links people have saved in the bookmarks/favourites on their home machines. They get dumped at the beginning of the page. You can raise or lower the importance of titles and sub-sub-headings such as from
===
to
=
or the other way around. Links still work then!
If you really have to change a page's name then please leave a redirect on the old page. It still messes people's links and they might well be annoyed but at least they get to the right new page that way.
Sorry for such a looong post :(
Regards from
Tom :)
>________________________________
> From: Laura Santamaria <nimbinatus at gmail.com>
>To: Benjamin Kerensa <bkerensa at ubuntu.com>
>Cc: ubuntu-doc at lists.ubuntu.com; Daniel Holbach <daniel.holbach at ubuntu.com>
>Sent: Tuesday, 26 March 2013, 1:30
>Subject: Re: Getting involved in the docs team
>
>
>Hello all,
>
>
>Long time lurker here who finally got time to start helping out with documentation in the past month (yay new job!). Upon spending some time reading through the same pages linked above during that period, I have to admit that it has not been easy to figure out how to start contributing. If I may lay out a couple places where, as a newbie, I have been having trouble, perhaps I can help with newbie documentation.
>
>
>First, I still have yet to figure out which markup I need to brush up on: Mallard or DocBook. They are both mentioned on the Doc Team pages (i.e., Mallard on https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation, but DocBook on https://wiki.ubuntu.com/DocumentationTeam). I have experience with both, but it has been a while. Considering I prefer to know a bit more about what I am getting into when I start a new project, knowing what markup to become familiar with before I start to dive in would be a great help. So are they both used? When is one used and not the other, if both are used?
>
>
>Second, where exactly *do* I start? I started by heading to "Join the Team" (https://wiki.ubuntu.com/DocumentationTeam/Organization), and, after joining the contributors on Launchpad, I clicked on the DocumentationTeam link, which took me to https://wiki.ubuntu.com/DocumentationTeam. That page does not have much for me to start with as I am not ready to be part of the Committers or the Wiki Admins. There's a short bit on the Beginners Team, but I have no reference as to who they are or who to get in contact with.
>
>
>When I head to the system documentation page (https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation) to see if there's some direction there, I see a list for proofreading, but the pages linked only look at 12.10. As I am looking to see if I can help with the next release cycle, I head to the Technical Review link (https://wiki.ubuntu.com/DocumentationTeam/TechReview), thinking perhaps that this is where I can start helping with 13.04. Here, though, if I am not using bzr, I get directed to http://doc.ubuntu.com/ubuntu/index.html, which takes me to 10.10 documentation. Hence, I am immediately confused.
>
>
>So I started poking around, trying to figure out where the information I need to really get started lies. I found a link on the Checking page (https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Checking) to a projects page. However, it does not exist: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Checking. Further poking around did not get me anywhere, either. Did I miss a page?
>
>
>So, onto Launchpad. I am not intimately familiar with it, but I am lucky to have someone in the house who is. However, there really are not any bugs listed for beginners--tagged as "documentor"--as described at (https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks). One link seems to not connect to the correct tag (?) at https://bugs.launchpad.net/ubuntu-docs/+bugs?field.tag=documentors. I have no idea what the error message "Ubuntu Documentation must be configured in order for Launchpad to forward bugs to the project's developers" means, by the way. The other link (https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/+bugs?field.tag=documentors) brings up one task, but it is a wishlist task that seems to have had a fix committed (though I may very well be reading it wrong) and has been outstanding since 2007 (!).
>
>
>So, what is a newbie to do? I have written documentation for my job, I am a professional editor, and I really, really love Ubuntu. I want to help. But how?
>
>
>Now, if the intention is to get interested parties to contact the list so that newbies can be closely watched--an intention I can understand from some projects I have worked on--then perhaps it needs to be clearly stated somewhere. I personally have not contacted the list as of yet due to (a) stubbornness as I like to believe I can figure things out for myself and (b) an awareness that perhaps a month before the next release is not the best time to be bugging busy people with new questions unless I am the only one writing documentation for said release.
>
>
>Does that help?
>
>
>Oh, and how do I start? :)
>
>
>Cheers,
>Laura
>
>
>P.S. - I did get the server guide email, and I am currently trying to get a VM up so I might get familiar with Ubuntu Server before volunteering. However, I did notice that the server guide page linked in that email does not seem to be easily reached from the standard pages. Was that intentional?
>
>
>
>On Mon, Mar 25, 2013 at 2:05 PM, Benjamin Kerensa <bkerensa at ubuntu.com> wrote:
>
>On Mon, Mar 25, 2013 at 10:23 AM, Daniel Holbach
>><daniel.holbach at ubuntu.com> wrote:
>>> On 25.03.2013 17:51, Daniel Holbach wrote:
>>>> Hello,
>>>>
>>>> On 22.03.2013 14:40, Daniel Holbach wrote:
>>>>> In the next update of ubuntu.com/community we want to bring the
>>>>> information of all kinds of teams into a form like over here:
>>>>> http://pad.ubuntu.com/communitywebsite-contribute-documentation
>>>>
>>>> I just went ahead and put together
>>>> http://pad.ubuntu.com/communitywebsite-contribute-documentation
>>>>
>>>> If somebody could please go and review it and add missing pieces, that'd
>>>> be wonderful.
>>>
>>> I just had a brief chat with Liz and she noted that the following bits
>>> and pieces were missing: "so the core stuff of what's missing from docs
>>> team stuff is launchpad (what branch to use?), mallard (but you mention
>>> docbook..?) and in general how this is all handled".
>>>
>>> What I probably should have mentioned in my first mail was that
>>> - on the wiki we'd like to have a bit more detail, like how to
>>> specifically get started, which branches, etc.
>>
>>This is covered on our /Repository page
>>https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository
>>
>>
>>> - on the pad page we'd like to have a bit more general
>>> information, be more introductory, so people get more
>>> interest in joining the team and excited about helping out
>>
>>Which pad page? We do have some info here which should be quite
>>helpful in getting people started
>>https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks
>>https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Editing
>>https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Checking
>>https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Submitting
>>https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/BuildingDocumentation
>>
>>I do think improvements are possible but in a nutshell contributing to
>>documentation from A to Z is there.... I think the biggest thing is
>>keeping tasks updated and just overall getting folks interested in
>>writing documentation.
>>
>>
>>
>>
>>>
>>> I hope that helps.
>>>
>>> Oh and please CC me on replies. :)
>>>
>>> Have a great day,
>>> Daniel
>>>
>>> --
>>> Get involved in Ubuntu development! developer.ubuntu.com/packaging
>>> Follow @ubuntudev on identi.ca/twitter.com/facebook.com/G+
>>>
>>> --
>>> ubuntu-doc mailing list
>>> ubuntu-doc at lists.ubuntu.com
>>> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>>
>>
>>
>>--
>>Benjamin Kerensa
>>http://benjaminkerensa.com
>>"I am what I am because of who we all are" - Ubuntu
>>
>>
>>--
>>ubuntu-doc mailing list
>>ubuntu-doc at lists.ubuntu.com
>>https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>>
>
>--
>ubuntu-doc mailing list
>ubuntu-doc at lists.ubuntu.com
>https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20130326/e0fa166a/attachment-0001.html>
More information about the ubuntu-doc
mailing list