Linux Archive

Linux Archive (http://www.linux-archive.org/)
-   Xubuntu Development (http://www.linux-archive.org/xubuntu-development/)
-   -   Documentation Rewrite Update (http://www.linux-archive.org/xubuntu-development/695763-documentation-rewrite-update.html)

Elizabeth Krumbach 08-20-2012 04:45 AM

Documentation Rewrite Update
 
Hi everyone,

Pasi Lallinaho has written a blog post explaining where we are with
the current documentation rewrite and explained how those who have
signed up to help with writing can pitch in now:

http://open.knome.fi/2012/08/17/working-on-the-xubuntu-documentation-rewrite/

We're still using the wiki that was set up, unfortunately there aren't
any simple tools for converting to Docbook that are currently
maintained, so this will be more of a manual process.

This all means that we really need to get the rewrite wrapped up with
in the next week or so if we want to have any hope of getting
editorial review and the conversion to Docbook done by September 20th.
We really need your help!

Thanks everyone, please feel free to ask if you have any questions.

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

--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Jack Fromm 08-21-2012 01:57 AM

Documentation Rewrite Update
 
Elizabeth and Pasi,

I'm willing to help and have some time but I'm still not clear on what I
can contribute and how. I volunteered as a Writer and Grammar Editor
and I made some minor punctuation and formatting edits to a couple
sections of the wiki tonight but I don't think that's really what you
need at this point. It sounds like the main thing you need right now is
to copy sections of the old documentation that have not been marked as
obsolete to the wiki and then start rewriting them. This is where I'm
unclear on how to proceed or even if I'm qualified. I know nothing
about Docbook so I thought I would try Pasi's alternative suggestion
(opening the Help file in my Xubuntu installation and copying and
pasting into the Wiki). But I quickly discovered two problems with
that. First, it means that all the formatting would have to be
completely re-done manually. Second, I don't know what guidelines you
are using for updating the content. For example, "Software
Repositories" in Section 10 of the old documentation has been copied to
Section 8 in the wiki, renamed "Additional Software Repositories" and
there are just three stub paragraphs in there that obviously need to be
fleshed out but which are also quite different from the old document.
Based on that example, I'm not sure how much help it would be to just
copy over sections from the old document. It sounds like you're aiming
for more of a major rewrite and not just a cleanup.


I hope I haven't completely misinterpreted what you're asking for. If
not, could you elaborate a little more on exactly what someone with my
skills should be doing to help move the project along?


Thanks,
Jack

On 08/20/2012 12:45 AM, Elizabeth Krumbach wrote:

Hi everyone,

Pasi Lallinaho has written a blog post explaining where we are with
the current documentation rewrite and explained how those who have
signed up to help with writing can pitch in now:

http://open.knome.fi/2012/08/17/working-on-the-xubuntu-documentation-rewrite/

We're still using the wiki that was set up, unfortunately there aren't
any simple tools for converting to Docbook that are currently
maintained, so this will be more of a manual process.

This all means that we really need to get the rewrite wrapped up with
in the next week or so if we want to have any hope of getting
editorial review and the conversion to Docbook done by September 20th.
We really need your help!

Thanks everyone, please feel free to ask if you have any questions.




--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Pasi Lallinaho 08-21-2012 09:16 AM

Documentation Rewrite Update
 
Hey Jack,

Copying and pasting old sections as-is is helpful too, because then it's
easier to just jump in to rewriting.

At this moment, you don't need to know anything about Docbook.
Everything is done with the wikimarkup. What comes about guidelines,
well, there isn't such. We create them on-the-fly.

A major rewrite is what we are aiming for, but that doesn't mean all
content is obsolete, or that we can't use what we've had before. Also,
don't worry too much about pages moving around; if you want to start,
just edit the page where it has been before. We can always move it
later, if we feel it fits a different section better.

I'm confident you have the skills to start writing. Even if you didn't
get everything right the first time, it's easier for us to polish things
than write everything on our own. There are now examples you can refer
to, or if you think none of those really fit the subject, feel free to
write as you think is better.

As I've implied before, the most important thing is just to start
working. We can adjust later.

If you need to know more, send another email or join us at
#xubuntu-devel for a live chat!

Cheers,
Pasi


On 08/21/2012 04:57 AM, Jack Fromm wrote:
> Elizabeth and Pasi,
>
> I'm willing to help and have some time but I'm still not clear on what
> I can contribute and how. I volunteered as a Writer and Grammar
> Editor and I made some minor punctuation and formatting edits to a
> couple sections of the wiki tonight but I don't think that's really
> what you need at this point. It sounds like the main thing you need
> right now is to copy sections of the old documentation that have not
> been marked as obsolete to the wiki and then start rewriting them.
> This is where I'm unclear on how to proceed or even if I'm qualified.
> I know nothing about Docbook so I thought I would try Pasi's
> alternative suggestion (opening the Help file in my Xubuntu
> installation and copying and pasting into the Wiki). But I quickly
> discovered two problems with that. First, it means that all the
> formatting would have to be completely re-done manually. Second, I
> don't know what guidelines you are using for updating the content.
> For example, "Software Repositories" in Section 10 of the old
> documentation has been copied to Section 8 in the wiki, renamed
> "Additional Software Repositories" and there are just three stub
> paragraphs in there that obviously need to be fleshed out but which
> are also quite different from the old document. Based on that
> example, I'm not sure how much help it would be to just copy over
> sections from the old document. It sounds like you're aiming for more
> of a major rewrite and not just a cleanup.
>
> I hope I haven't completely misinterpreted what you're asking for. If
> not, could you elaborate a little more on exactly what someone with my
> skills should be doing to help move the project along?
>
> Thanks,
> Jack
>
> On 08/20/2012 12:45 AM, Elizabeth Krumbach wrote:
>> Hi everyone,
>>
>> Pasi Lallinaho has written a blog post explaining where we are with
>> the current documentation rewrite and explained how those who have
>> signed up to help with writing can pitch in now:
>>
>> http://open.knome.fi/2012/08/17/working-on-the-xubuntu-documentation-rewrite/
>>
>>
>> We're still using the wiki that was set up, unfortunately there aren't
>> any simple tools for converting to Docbook that are currently
>> maintained, so this will be more of a manual process.
>>
>> This all means that we really need to get the rewrite wrapped up with
>> in the next week or so if we want to have any hope of getting
>> editorial review and the conversion to Docbook done by September 20th.
>> We really need your help!
>>
>> Thanks everyone, please feel free to ask if you have any questions.
>>
>
>


--
Pasi Lallinaho (knome) http://open.knome.fi/
Leader of Shimmer Project and Xubuntu http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member http://xubuntu.org/


--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Jack Fromm 08-21-2012 02:46 PM

Documentation Rewrite Update
 
On 08/21/2012 05:16 AM, Pasi Lallinaho wrote:

Hey Jack,

Copying and pasting old sections as-is is helpful too, because then it's
easier to just jump in to rewriting.

At this moment, you don't need to know anything about Docbook.
Everything is done with the wikimarkup. What comes about guidelines,
well, there isn't such. We create them on-the-fly.

A major rewrite is what we are aiming for, but that doesn't mean all
content is obsolete, or that we can't use what we've had before. Also,
don't worry too much about pages moving around; if you want to start,
just edit the page where it has been before. We can always move it
later, if we feel it fits a different section better.

I'm confident you have the skills to start writing. Even if you didn't
get everything right the first time, it's easier for us to polish things
than write everything on our own. There are now examples you can refer
to, or if you think none of those really fit the subject, feel free to
write as you think is better.

As I've implied before, the most important thing is just to start
working. We can adjust later.

If you need to know more, send another email or join us at
#xubuntu-devel for a live chat!

Cheers,
Pasi
Okay, I'll give it a go. I'll try starting with Section 10. Keeping
Your Computer Safe. I'll just copy over the old sub-sections first.
Then I'll start going through them to see what needs updating. If
anyone thinks I'm going about it wrong, please point me in the right
direction.


Jack

--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Pasi Lallinaho 08-21-2012 09:56 PM

Documentation Rewrite Update
 
I see you copied the old text over - great! I've rewritten one of the
subpages as an additional example for you (and others) on how to get
started with the actual rewrite.


Again, please don't hesitate to be in touch.

Cheers,
Pasi

On 21/08/12 12:16, Pasi Lallinaho wrote:

Hey Jack,

Copying and pasting old sections as-is is helpful too, because then it's
easier to just jump in to rewriting.

At this moment, you don't need to know anything about Docbook.
Everything is done with the wikimarkup. What comes about guidelines,
well, there isn't such. We create them on-the-fly.

A major rewrite is what we are aiming for, but that doesn't mean all
content is obsolete, or that we can't use what we've had before. Also,
don't worry too much about pages moving around; if you want to start,
just edit the page where it has been before. We can always move it
later, if we feel it fits a different section better.

I'm confident you have the skills to start writing. Even if you didn't
get everything right the first time, it's easier for us to polish things
than write everything on our own. There are now examples you can refer
to, or if you think none of those really fit the subject, feel free to
write as you think is better.

As I've implied before, the most important thing is just to start
working. We can adjust later.

If you need to know more, send another email or join us at
#xubuntu-devel for a live chat!

Cheers,
Pasi


On 08/21/2012 04:57 AM, Jack Fromm wrote:

Elizabeth and Pasi,

I'm willing to help and have some time but I'm still not clear on what
I can contribute and how. I volunteered as a Writer and Grammar
Editor and I made some minor punctuation and formatting edits to a
couple sections of the wiki tonight but I don't think that's really
what you need at this point. It sounds like the main thing you need
right now is to copy sections of the old documentation that have not
been marked as obsolete to the wiki and then start rewriting them.
This is where I'm unclear on how to proceed or even if I'm qualified.
I know nothing about Docbook so I thought I would try Pasi's
alternative suggestion (opening the Help file in my Xubuntu
installation and copying and pasting into the Wiki). But I quickly
discovered two problems with that. First, it means that all the
formatting would have to be completely re-done manually. Second, I
don't know what guidelines you are using for updating the content.
For example, "Software Repositories" in Section 10 of the old
documentation has been copied to Section 8 in the wiki, renamed
"Additional Software Repositories" and there are just three stub
paragraphs in there that obviously need to be fleshed out but which
are also quite different from the old document. Based on that
example, I'm not sure how much help it would be to just copy over
sections from the old document. It sounds like you're aiming for more
of a major rewrite and not just a cleanup.

I hope I haven't completely misinterpreted what you're asking for. If
not, could you elaborate a little more on exactly what someone with my
skills should be doing to help move the project along?

Thanks,
Jack

On 08/20/2012 12:45 AM, Elizabeth Krumbach wrote:

Hi everyone,

Pasi Lallinaho has written a blog post explaining where we are with
the current documentation rewrite and explained how those who have
signed up to help with writing can pitch in now:

http://open.knome.fi/2012/08/17/working-on-the-xubuntu-documentation-rewrite/


We're still using the wiki that was set up, unfortunately there aren't
any simple tools for converting to Docbook that are currently
maintained, so this will be more of a manual process.

This all means that we really need to get the rewrite wrapped up with
in the next week or so if we want to have any hope of getting
editorial review and the conversion to Docbook done by September 20th.
We really need your help!

Thanks everyone, please feel free to ask if you have any questions.








--
Pasi Lallinaho (knome) http://open.knome.fi/
Leader of Shimmer Project and Xubuntu http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member http://xubuntu.org/


--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Jack Fromm 08-22-2012 01:53 AM

Documentation Rewrite Update
 
Okay, I looked over your rewrite to get a feel for what you wanted. It
seems like you want to make this new version much more concise than the
old one by eliminating a lot of the step-by-step details on how to
accomplish things. Is that accurate?


I've been working on a few more of the subpages under section 10.
Mostly I've just tried to make the formatting consistent with the other
sections but I've also been checking to make sure the references to
fields, choices and buttons match the Quantal wording wherever that has
changed. So it still might be too wordy if you really are trying to
tighten things up. Let me know if that's the case.


Thanks for you patience.
Jack

On 08/21/2012 05:56 PM, Pasi Lallinaho wrote:
I see you copied the old text over - great! I've rewritten one of the
subpages as an additional example for you (and others) on how to get
started with the actual rewrite.


Again, please don't hesitate to be in touch.

Cheers,
Pasi




--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Elfy 08-22-2012 06:23 AM

Documentation Rewrite Update
 
On 21/08/12 22:56, Pasi Lallinaho wrote:
I see you copied the old text over - great! I've rewritten one of the
subpages as an additional example for you (and others) on how to get
started with the actual rewrite.


Again, please don't hesitate to be in touch.

Cheers,
Pasi


So we know what you are after - which page did you rewrite :)

Elfy

--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Pasi Lallinaho 08-22-2012 09:27 AM

Documentation Rewrite Update
 
On 22/08/12 09:23, Elfy wrote:

On 21/08/12 22:56, Pasi Lallinaho wrote:
I see you copied the old text over - great! I've rewritten one of the
subpages as an additional example for you (and others) on how to get
started with the actual rewrite.


Again, please don't hesitate to be in touch.

Cheers,
Pasi


So we know what you are after - which page did you rewrite :)

Elfy



I moved the "Passwords" page right under "Keeping your computer safe".

Cheers,
Pasi

--
Pasi Lallinaho (knome) http://open.knome.fi/
Leader of Shimmer Project and Xubuntu http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member http://xubuntu.org/


--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Pasi Lallinaho 08-22-2012 09:30 AM

Documentation Rewrite Update
 
Hey Jack!

Yes, if making it a bit more concise doesn't make it harder to follow,
I'm encouraging you to do that.


Cheers,
Pasi

On 22/08/12 04:53, Jack Fromm wrote:
Okay, I looked over your rewrite to get a feel for what you wanted.
It seems like you want to make this new version much more concise than
the old one by eliminating a lot of the step-by-step details on how to
accomplish things. Is that accurate?


I've been working on a few more of the subpages under section 10.
Mostly I've just tried to make the formatting consistent with the
other sections but I've also been checking to make sure the references
to fields, choices and buttons match the Quantal wording wherever that
has changed. So it still might be too wordy if you really are trying
to tighten things up. Let me know if that's the case.


Thanks for you patience.
Jack

On 08/21/2012 05:56 PM, Pasi Lallinaho wrote:
I see you copied the old text over - great! I've rewritten one of the
subpages as an additional example for you (and others) on how to get
started with the actual rewrite.


Again, please don't hesitate to be in touch.

Cheers,
Pasi







--
Pasi Lallinaho (knome) http://open.knome.fi/
Leader of Shimmer Project and Xubuntu http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member http://xubuntu.org/


--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel


All times are GMT. The time now is 05:52 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.