[Frugalware-devel] Proposed restructuring of documentation

Russell Dickenson russelldickenson at gmail.com
Wed Mar 24 23:48:05 CET 2010


On 23 March 2010 09:53, Miklos Vajna <vmiklos at frugalware.org> wrote:
> On Mon, Mar 15, 2010 at 04:01:08PM +1000, Russell Dickenson <russelldickenson at gmail.com> wrote:
>> > If you want to do some kind of restructure, then probably the most
>> > important part would be to split the administration and user part, as we
>> > only have user and developer documentation. If you say chapter "foo" and
>> > "bar" should go to the admin doc from the user doc, I can help creating
>> > the first version of the admin part, as the buildsystem is indeed a bit
>> > tricky, as Pete pointed out. :) [ Currently we have index-user.txt and
>> > index-devel.txt and links are pointing from those docs to individual
>> > chapters. Once there is an index-admin.txt with a few chapters, it's
>> > easy to add new chapters to it. ]
>>
>> I don't quite understand what you mean by "administration". Which
>> parts of the existing documentation relate to administration?
>
> Currently there is no 'administration' section, but think this a typical
> administrative task is:
>
> - how to install on raid1
> - how to back up your system using rdiff-backup
>
> A typical user section is:
>
> - how do I set the file associations in nautilus / dolphin so that .doc
>  is opened by $my_favorite_editor and not OOo

OK - now I understand a little better.


>> I plan to approach the documentation review and revision in several
>> large chunks, instead of trying to do it in one large piece of work.
>> >From a git perspective I guess I will finally be making use of
>> branches? For example, a restructuring of the current index might be
>> one branch, and the revision of the text might be in another branch.
>> Does this make sense or do I misunderstand the concept of a "branch"?
>
> You are right, but right now we use branches in the following situation:
>
> We introduce a breakage intentionally then we fix it up during the next
> few days / weeks. When we think we fixed everything, we merge the
> branch, so that users will always have a working system, as large
> changes are uploaded to -current at once.
>
> Given that you want to work on documentation which does not introduce
> such a breakage, I would not say it's necessary that you work in a
> separate branch. (You can, but given that I expect it would make your
> life unnecessarily complex, I would not recommend it.)

OK. If I understand correctly then, you're OK if I make individual
changes to the documentation in the "main" branch. When 1.3 is
released, the documentation will be snapshot at that point and become
the "stable" documentation, as referred to on the following page -

http://frugalware.org/docs

I don't like seeing a reference to "stable" and "development"
documentation on this page. I believe we have discussed it before and
the stable documentation is the documentation for whatever is the
stable release - currently 1.2 - while the development documentation
may change as the distribution changes, for example as PulseAudio is
added. For users who simply want to use Frugalware for their daily
tasks, I think this is confusing. I see to options: (1) remove links
to the development documentation, (2) add more information to the page
which explains the purpose of the two "copies" of the documentation.

I know I have written emails about Frugalware's documentation while
not being able to show any results from those discussions. I
appreciate your patience and hope to soon produce something.


May you always be Frugal,

Russell Dickenson (AKA phayz)


More information about the Frugalware-devel mailing list