Linux Archive

Linux Archive (http://www.linux-archive.org/)
-   Xubuntu Development (http://www.linux-archive.org/xubuntu-development/)
-   -   Documentation; GO! (http://www.linux-archive.org/xubuntu-development/689667-documentation-go.html)

Pasi Lallinaho 08-01-2012 08:10 PM

Documentation; GO!
 
Hello Xubuntu
documentation enthusiasts!



It's time for
the next step in the documentation rewrite. Those who signed up
as Writers or Technical
Editors, it's time for
you to shine! Soon, Grammar
Editors can chime in
too!



There are
few things we need to get sorted out next. These are listed
underneath. The roles in the parenthesis mean the primary groups
that should undertake these tasks, but you can help out even if
you didn't list in that group too.



What we need to
do now is:
– Copy the
current documentation to the wiki (Everybody,
where applicable)
– Review the
documentation structure (Technical
Editors)
** – Is the
documentation structure good, or should we reorganize? (Technical Editors)
** – Do we have any
redundant information in the documentation? (Technical
Editors)
** – Should we add
something else to the documentation? (Technical
Editors)
– Does the
documentation match the current state or applications? (Technical Editors)
** – If not;
rewrite the section and once the sections are rewritten, check
them for grammar errors (Writers, Grammar Editors)
** – If yes; make
sure it's clearly written and check for possible grammar errors
(Grammar Editors)



We have put
together a temporary wiki for this work to be done on here: http://dagobah.princessleia.com/Xubuntu. We've set up
a few sections as examples on how to add the content to the
wiki. Follow the examples, or if you think you can do it better,
feel free to!



Please don't
be shy about
starting edits, but keep in mind that this is collaborative so
you will want to coordinate with other documentation writers on
the xubuntu-devel mailing list when discussing deletions or
major changes to sections. You may also consider splitting up
"ownership" of the sections so only one person is working on
them at once, that's up to you – the docs
team!



The original
documentation can be found in Docbook format at https://code.launchpad.net/xubuntu-docs (useful for
those who want to learn Docbook – those who signed up as Docbook
Editors). If you're scared of Docbook, you can also use the
offline menu in your installation; just navigatie to Help in the
applications menu and it will
bring up the documentation in a web browser.



Finally,
please note that Xubuntu does not currently have Documentation
Lead, which means we're feeling our way here and just beginning
to build up what the
documentation
infrastructure and the conventions are. Suggestions
welcome!
(Eventually, we might pick a Documentation Lead if there is
people willing and able to take that position.)



However, if
any kind of questions or disputes arise, you are very welcome to
send email to the xubuntu-devel mailing list. Ultimately, there
are two people resolving disputes and other issues; Pasi
Lallinaho, the Project Lead and Elizabeth Krumbach, the
Marketing Lead.



Please note
that it's
summer time in the northern hemisphere so we have a lot of
project members traveling and generally just having holidays in
the coming weeks and we don't want anyone feeling held up
because they didn't get a response.



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

Paulo Ribeiro 08-02-2012 11:03 AM

Documentation; GO!
 
Hello everybody!

The first task of copying the documentation to the wiki seems practical
and simple enough. I will be sure to help with that as time allows.


In the meanwhile, I made a copy of the latest Xubuntu documentation
available on my site so that I can access it even when I'm not on
Xubuntu. Perhaps it can be useful to other people as well:


http://diffraction.pt/misc/xubuntu-docs/

I hope to see the discussion about the documentation structure and
content starting soon. :)


Regards,

--
Paulo Ribeiro

On 12.Aug.01 21:10, Pasi Lallinaho wrote:

Hello Xubuntu documentation enthusiasts!

It's time for the next step in the documentation rewrite. Those who
signed up as *Writers*or *Technical Editors*, it's time for you to
shine! Soon, *Grammar Editors*can chime in too!

There are few things we need to get sorted out next. These are listed
underneath. The roles in the parenthesis mean the primary groups that
should undertake these tasks, but you can help out even if you didn't
list in that group too.

What we need to do now is:
– Copy the current documentation to the wiki (Everybody, where applicable)
– Review the documentation structure (Technical Editors)
– Is the documentation structure good, or should we reorganize?
(Technical Editors)
–Do we have any redundant information in the documentation? (Technical
Editors)
–Should we add something else to the documentation? (Technical Editors)
– Does the documentation match the current state or applications?
(Technical Editors)
–If not; rewrite the section and once the sections are rewritten, check
them for grammar errors (Writers, Grammar Editors)
–If yes; make sure it's clearly written and check for possible grammar
errors (Grammar Editors)

We have put together a temporary wiki for this work to be done on here:
http://dagobah.princessleia.com/Xubuntu. We've set up a few sections as
examples on how to add the content to the wiki. Follow the examples, or
if you think you can do it better, feel free to!

Please don't beshy about starting edits, but keep in mind that this is
collaborative so you will want to coordinate with other documentation
writers on the xubuntu-devel mailing list when discussing deletions or
major changes to sections. You may also consider splitting up
"ownership" of the sections so only one person is working on them at
once, that's up to you –the docs team!

The original documentation can be found in Docbook format at
https://code.launchpad.net/xubuntu-docs(useful for those who want to
learn Docbook – those who signed up as Docbook Editors). If you're
scared of Docbook, you can also use the offline menu in your
installation; just navigatie to Help in the applications menuand it will
bring up the documentation in a web browser.

Finally, please note that Xubuntu does not currently have Documentation
Lead, which means we're feeling our way here and just beginning to build
upwhat the documentationinfrastructure and the conventions are.
Suggestions welcome!(Eventually, we might pick a Documentation Lead if
there is people willing and able to take that position.)

However, if any kind of questions or disputes arise, you are very
welcome to send email to the xubuntu-devel mailing list. Ultimately,
there are two people resolving disputes and other issues; Pasi
Lallinaho, the Project Lead and Elizabeth Krumbach, the Marketing Lead.

Please note that it's summer time in the northern hemisphere so we have
a lot of project members traveling and generally just having holidays in
the coming weeks and we don't want anyone feeling held up because they
didn't get a response.

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

Elizabeth Krumbach 08-02-2012 05:59 PM

Documentation; GO!
 
On Thu, Aug 2, 2012 at 4:03 AM, Paulo Ribeiro <paulo@diffraction.pt> wrote:
> The first task of copying the documentation to the wiki seems practical and
> simple enough. I will be sure to help with that as time allows.

I tried to use some scripts to convert both docbook and html to wiki
syntax and it wasn't as straight forward as I had hoped. Before
spending too much time on this I would recommend coming up with a
methodology for what to copy over. Does a page look good and not need
updating? Maybe not copy that one over. Or maybe just copy over
sections you intend to work on?

It's also worth noting that while I set up the wiki, we don't have to
use it if people find it too cumbersome. If someone has better ideas
for how to collaborate on this or wants different software installed
that's perfectly fine (the server is running Debian 6.0). I can even
give folks shell accounts if you'd rather work directly with flat
html. All up to you.

Thanks.

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

Paulo Ribeiro 08-02-2012 07:49 PM

Documentation; GO!
 
I also thought about automatizing the process of copying the current
documentation to the wiki (for example, using regular expressions to
convert HTML into wiki syntax), but I also think it is not very
straightforward because the two syntaxes are not equivalent.


I think that if we had the entire documentation in the wiki it would be
easier to propose macro level changes to the documentation (such as
changes in the structure of the topics, organization of information, and
so on).


I'm not sure how many people are interested in participating on this
project, but if each person would copy a small subset of the
documentation topics to the wiki then we could have a collaborative
platform ready in a very short time.


--
Paulo Ribeiro

On 12.08.02 18:59, Elizabeth Krumbach wrote:

On Thu, Aug 2, 2012 at 4:03 AM, Paulo Ribeiro <paulo@diffraction.pt> wrote:

The first task of copying the documentation to the wiki seems practical and
simple enough. I will be sure to help with that as time allows.


I tried to use some scripts to convert both docbook and html to wiki
syntax and it wasn't as straight forward as I had hoped. Before
spending too much time on this I would recommend coming up with a
methodology for what to copy over. Does a page look good and not need
updating? Maybe not copy that one over. Or maybe just copy over
sections you intend to work on?

It's also worth noting that while I set up the wiki, we don't have to
use it if people find it too cumbersome. If someone has better ideas
for how to collaborate on this or wants different software installed
that's perfectly fine (the server is running Debian 6.0). I can even
give folks shell accounts if you'd rather work directly with flat
html. All up to you.

Thanks.



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

Paulo Ribeiro 08-02-2012 08:15 PM

Documentation; GO!
 
Come to think of it, the optimal solution is one that would allow
collaboration directly over the DocBook source files.


I did a quick search and found a wiki application that allows displaying
and editing DocBook documents online:


http://sourceforge.net/projects/doc-book/

I can check if this is a viable solution as soon as I have the time, or
we could search for other similar tools that would allow us to work
collaboratively directly over DocBook...


--
Paulo Ribeiro

On 12.08.02 20:49, Paulo Ribeiro wrote:

I also thought about automatizing the process of copying the current
documentation to the wiki (for example, using regular expressions to
convert HTML into wiki syntax), but I also think it is not very
straightforward because the two syntaxes are not equivalent.

I think that if we had the entire documentation in the wiki it would be
easier to propose macro level changes to the documentation (such as
changes in the structure of the topics, organization of information, and
so on).

I'm not sure how many people are interested in participating on this
project, but if each person would copy a small subset of the
documentation topics to the wiki then we could have a collaborative
platform ready in a very short time.



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

Elizabeth Krumbach 08-02-2012 08:21 PM

Documentation; GO!
 
On Thu, Aug 2, 2012 at 1:15 PM, Paulo Ribeiro <paulo@diffraction.pt> wrote:
> I did a quick search and found a wiki application that allows displaying and
> editing DocBook documents online:
>
> http://sourceforge.net/projects/doc-book/
>
> I can check if this is a viable solution as soon as I have the time,

Oh, very cool! Thanks for taking the time to look into this, looking
forward to seeing what you find.

> or we
> could search for other similar tools that would allow us to work
> collaboratively directly over DocBook...

The goal at this stage is really making the docs easy to collaborate
on (manually editing docbook files isn't easy), but if we actually
could keep it all in docbook through the whole process, while keeping
it easy for people, that'd be fantastic.

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

Paulo Ribeiro 08-07-2012 10:01 AM

Documentation; GO!
 
Hello again,

Over the weekend I managed to install the DocBookWiki application on a
Ubuntu Server 10.04 machine, but unfortunately I couldn't get the
application to work. I suspect that DocBookWiki is no longer compatible
either with phpWebApp, which is one of the dependencies, or with PHP 5.


Furthermore, the project isn't actively maintained for at least 4 years
(http://sourceforge.net/mailarchive/forum.php?thread_name=b321594e0803040804l3807d216j fe00ae936f927206%40mail.gmail.com&forum_name=doc-book-users),
which limits the option of asking for support.


Interestingly, I found an old blog post by Mark Shuttleworth where he
poses the same requirements as the Xubuntu Documentation project:


http://www.markshuttleworth.com/archives/59

There are many suggestions of tools to do the job in the comments,
including the built-in DocBook support of MoinMoin, which sounds promising.


Perhaps someone is already familiarized with one of the suggested tools
and could give any advice about using them in the Documentation project?


--
Paulo Ribeiro

On 12.Aug.02 21:21, Elizabeth Krumbach wrote:

On Thu, Aug 2, 2012 at 1:15 PM, Paulo Ribeiro <paulo@diffraction.pt> wrote:

I did a quick search and found a wiki application that allows displaying and
editing DocBook documents online:

http://sourceforge.net/projects/doc-book/

I can check if this is a viable solution as soon as I have the time,


Oh, very cool! Thanks for taking the time to look into this, looking
forward to seeing what you find.


or we
could search for other similar tools that would allow us to work
collaboratively directly over DocBook...


The goal at this stage is really making the docs easy to collaborate
on (manually editing docbook files isn't easy), but if we actually
could keep it all in docbook through the whole process, while keeping
it easy for people, that'd be fantastic.



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

Elizabeth Krumbach 08-11-2012 09:31 PM

Documentation; GO!
 
On Tue, Aug 7, 2012 at 3:01 AM, Paulo Ribeiro <paulo@diffraction.pt> wrote:
> Hello again,
>
> Over the weekend I managed to install the DocBookWiki application on a
> Ubuntu Server 10.04 machine, but unfortunately I couldn't get the
> application to work. I suspect that DocBookWiki is no longer compatible
> either with phpWebApp, which is one of the dependencies, or with PHP 5.
>
> Furthermore, the project isn't actively maintained for at least 4 years
> (http://sourceforge.net/mailarchive/forum.php?thread_name=b321594e0803040804l3807d216j fe00ae936f927206%40mail.gmail.com&forum_name=doc-book-users),
> which limits the option of asking for support.

Thanks for spending the time on this!

> Interestingly, I found an old blog post by Mark Shuttleworth where he poses
> the same requirements as the Xubuntu Documentation project:
>
> http://www.markshuttleworth.com/archives/59
>
> There are many suggestions of tools to do the job in the comments, including
> the built-in DocBook support of MoinMoin, which sounds promising.
>
> Perhaps someone is already familiarized with one of the suggested tools and
> could give any advice about using them in the Documentation project?

I'm not sure such a person exists who is available right now :)

Looking at this project, it's quite a big one and docs freeze is on
September 20th so we really want to get moving forward soon so we can
get this in on time.

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

Rich Dennis 08-28-2012 10:35 PM

Documentation; GO!
 
On 08/01/2012 04:10 PM, Pasi Lallinaho
wrote:




Hello Xubuntu
documentation enthusiasts!



It's time for
the next step in the documentation rewrite. Those who signed
up as Writers or Technical

Editors, it's time
for you to shine! Soon, Grammar
Editors can chime in
too!



There are
few things we need to get sorted out next. These are listed
underneath. The roles in the parenthesis mean the primary
groups that should undertake these tasks, but you can help out
even if you didn't list in that group too.



What we need
to do now is:
– Copy the
current documentation to the wiki (Everybody,

where applicable)
– Review the
documentation structure (Technical
Editors)
** – Is the
documentation structure good, or should we reorganize? (Technical
Editors)
** – Do we have
any redundant information in the documentation? (Technical
Editors)
** – Should we
add something else to the documentation? (Technical
Editors)
– Does the
documentation match the current state or applications? (Technical
Editors)
** – If not;
rewrite the section and once the sections are rewritten, check
them for grammar errors (Writers, Grammar Editors)
** – If yes; make
sure it's clearly written and check for possible grammar
errors (Grammar Editors)



We have
put together a temporary wiki for this work to be done on
here: http://dagobah.princessleia.com/Xubuntu. We've set
up a few sections as examples on how to add the content to the
wiki. Follow the examples, or if you think you can do it
better, feel free to!



Please
don't be shy about
starting edits, but keep in mind that this is collaborative so
you will want to coordinate with other documentation writers
on the xubuntu-devel mailing list when discussing deletions or
major changes to sections. You may also consider splitting up
"ownership" of the sections so only one person is working on
them at once, that's up to you – the docs
team!



The original
documentation can be found in Docbook format at https://code.launchpad.net/xubuntu-docs (useful for
those who want to learn Docbook – those who signed up as
Docbook Editors). If you're scared of Docbook, you can also
use the offline menu in your installation; just navigatie to
Help in the applications menu and it
will bring up the documentation in a web browser.



Finally,
please note that Xubuntu does not currently have Documentation
Lead, which means we're feeling our way here and just
beginning to build up what the
documentation
infrastructure and the conventions are. Suggestions

welcome!
(Eventually, we might pick a Documentation Lead if there is
people willing and able to take that position.)



However,
if any kind of questions or disputes arise, you are very
welcome to send email to the xubuntu-devel mailing list.
Ultimately, there are two people resolving disputes and other
issues; Pasi Lallinaho, the Project Lead and Elizabeth
Krumbach, the Marketing Lead.



Please
note that it's
summer time in the northern hemisphere so we have a lot of
project members traveling and generally just having holidays
in the coming weeks and we don't want anyone feeling held up
because they didn't get a response.



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/







Went on #xubuntu-devel this morning. Don't think that I have what it
takes to do Docbook rewrites, but if you need any writers or grammar
editors, I would very much like to contribute.

Thanks. rd - amerigena



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

Pasi Lallinaho 08-29-2012 05:37 AM

Documentation; GO!
 
On 08/29/2012 01:35 AM, Rich Dennis
wrote:




On 08/01/2012 04:10 PM, Pasi
Lallinaho wrote:




Hello
Xubuntu documentation enthusiasts!



It's time
for the next step in the documentation rewrite. Those who
signed up as Writers or Technical


Editors, it's time
for you to shine! Soon, Grammar

Editors can chime
in too!



There
are few things we need to get sorted out next. These are
listed underneath. The roles in the parenthesis mean the
primary groups that should undertake these tasks, but you
can help out even if you didn't list in that group too.



What we
need to do now is:
– Copy the
current documentation to the wiki (Everybody,


where applicable)
– Review
the documentation structure (Technical

Editors)
** – Is the
documentation structure good, or should we reorganize? (Technical

Editors)
** – Do we have
any redundant information in the documentation? (Technical

Editors)
** – Should we
add something else to the documentation? (Technical

Editors)
– Does the
documentation match the current state or applications? (Technical

Editors)
** – If not;
rewrite the section and once the sections are rewritten,
check them for grammar errors (Writers, Grammar
Editors)
** – If yes;
make sure it's clearly written and check for possible
grammar errors (Grammar
Editors)



We have
put together a temporary wiki for this work to be done on
here: http://dagobah.princessleia.com/Xubuntu. We've set
up a few sections as examples on how to add the content to
the wiki. Follow the examples, or if you think you can do it
better, feel free to!



Please
don't be shy
about starting edits, but keep in mind that this is
collaborative so you will want to coordinate with other
documentation writers on the xubuntu-devel mailing list when
discussing deletions or major changes to sections. You may
also consider splitting up "ownership" of the sections so
only one person is working on them at once, that's up to you
– the
docs team!



The
original documentation can be found in Docbook format at https://code.launchpad.net/xubuntu-docs (useful
for those who want to learn Docbook – those who signed up as
Docbook Editors). If you're scared of Docbook, you can also
use the offline menu in your installation; just navigatie to
Help in the applications menu and it
will bring up the documentation in a web browser.



Finally,

please note that Xubuntu does not currently have
Documentation Lead, which means we're feeling our way here
and just beginning to build up what
the documentation
infrastructure and the conventions are. Suggestions


welcome!
(Eventually, we might pick a Documentation Lead if there is
people willing and able to take that position.)



However,

if any kind of questions or disputes arise, you are very
welcome to send email to the xubuntu-devel mailing list.
Ultimately, there are two people resolving disputes and
other issues; Pasi Lallinaho, the Project Lead and Elizabeth
Krumbach, the Marketing Lead.



Please
note that it's
summer time in the northern hemisphere so we have a lot of
project members traveling and generally just having holidays
in the coming weeks and we don't want anyone feeling held up
because they didn't get a response.



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/







Went on #xubuntu-devel this morning. Don't think that I have what
it takes to do Docbook rewrites, but if you need any writers or
grammar editors, I would very much like to contribute.

Thanks. rd - amerigena









Help with writing and that stuff is welcome too! See the first part
of my last mail [1] for a quick introduction to the current
situation and you are ready to start working.



Cheers,

Pasi



[1]
https://lists.ubuntu.com/archives/xubuntu-devel/2012-August/008392.html



--
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 02:50 AM.

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