Documentation Rewrite Update

Pasi Lallinaho pasi at shimmerproject.org
Tue Aug 21 09:16:28 UTC 2012


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/





More information about the xubuntu-devel mailing list