[scotthomas]

Hi there.

I'm posting here to offer my services to help with any documentation work for this project. I'm a Content Author for Red Hat and an ex-Songbird user.

Songbird was a revelation to me and it quickly became my media player of choice. I was a little heartbroken when Linux support was pulled. Which is why I desperately want to see this project succeed, and hence why I'm volunteering my services.

I was hoping someone could fill me in on how documentation is (will be?) handled for Nightingale and, if I can be of use, how I might get started.

Cheers from Down Under.

[ilikenwf]

Right now, we just have a wiki and a bunch of guys that hang out on the forums and IRC...haha...

If you have any requests in terms of some sort of documentation managment system or something, please speak, as a lot of us are just coders and designers and don't know the first thing about writing human readable docs...

[scotthomas]

(03-09-2012, 03:46 PM)ilikenwf Wrote: Right now, we just have a wiki

If you have any requests in terms of some sort of documentation managment system or something, please speak

Hey ilikenwf
Thanks for the quick reply.

I don't really have any requests, I'm happy to work with whatever systems are already in place. If there isn't any definite workflows set up yet, I can produce chunked html, single-page html and PDF versions of any docs that you guys might want.

To get started, how about I convert some of the content from the wiki to one of the formats above, and host it somewhere, then you guys can check it out and see if it works for you?

[ilikenwf]

Before you do, I'd like to hear from GeekShadow and rsjtdrjgfuzkfg about this, they usually have good input.

[rsjtdrjgfuzkfg]

I'm glad we have you here, as we don't have writers for documentation yet.
As ilikenwf pointed out, the people currently behind Nightingale are coders, designers and testers only, we have a lack of documentation writers.

I personally would like to keep the stuff in the wiki, but I'm not sure if our Wiki has a possibility to export if we should change the system in the future, and what kind of privilege-management is possible (@GeekShadow?). Currently that doesn't matter that much, but we might as well use another system to prevent later issues.

Basically, a wiki is more easy to update as a set of HTML or a PDF, if we need one of that I think many HTML pages in a git repo are the way to go. Can you explain why you suggested these formats? Maybe you can either convince me or it helps us to find the ideal solution.
However, we might write a script exporting our wiki content to one or more of the formats you suggested, for offline reading. I agree that a PDF is nicer to handle for offline reading than a copy of raw wiki pages.

[ilikenwf]

...and it would actually be nice to have a downloadable copy of the documentation...HTML or pdf...

If the current wiki doesn't support basic HTML, we could probably use or build a little CMS or find another wiki for it...

[scotthomas]

(03-10-2012, 10:12 PM)rsjtdrjgfuzkfg Wrote: I'm glad we have you here, as we don't have writers for documentation yet.

I'm glad to be here and hope I can be of use to the project and stay involved for a while.

I agree that, if you're expecting input from a lot of documentation contributors, a wiki is a much better option than cold-creating HTML or PDF docs.

However, if you're expecting that docs work will come from a small subset of contributors and that most readers will be end-users of the product (which I imagine might be the case with Nightingale), setting up a system which produces end-user-friendly doc formats (HTML/PDF) is a sound strategy.

The best path for Nightingale will depend on how the team sees the documentation effort being executed in the future. Any ideas on that?

---

(03-11-2012, 04:51 AM)ilikenwf Wrote: If the current wiki doesn't support basic HTML, we could probably ... find another wiki for it...

If I'm not getting ahead of myself with this; Atlassian offers a great wiki product called Confluence that is easy to use, scales well and is free for open source projects.

It also has a well-supported export-to-xml tool which would allow someone like me to create branded HTML and PDF versions within minutes.

Best of both worlds?

[ilikenwf]

I always saw the wiki as becoming more of a resource for developers down the line, with separate docs for end users...but again, I need to hear from the other guys on it.

Confluence sounds good as long as it's php/mysql, as we currently don't have our own servers...

[freaktechnik]

Well, I think we should maintain two ressources: A Developer documentation (which is written by devs) and something like a user-friendly wiki, which contains the how-tos etc. So I agree with setting off another wiki/cms whatever system.

[rsjtdrjgfuzkfg]

(03-12-2012, 09:44 PM)freaktechnik Wrote: Well, I think we should maintain two ressources: A Developer documentation (which is written by devs) and something like a user-friendly wiki, which contains the how-tos etc. So I agree with setting off another wiki/cms whatever system.

If it is possible, I think doing it in the same system is ok, too. And we don't need to set anything up, think about how to link it, etc. What about a help: and a dev: namespace in the current wiki?