Quantcast

[Mondo-devel] FAQ and Doc.

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[Mondo-devel] FAQ and Doc.

Bruno Cornec-2
Hello,

Following some exchanges with Victor (co-maintainer) and the mail of
Tom:

> And this raises another suggestion: multiple FAQs are almost worse than
> no FAQs. If the Trac ones superseded the ones on the main site, then
> replace the one on the main site with a link to the Trac pages.

I think it's time for a documentation revamp phase.
My goals are in order:

1/ Unify the 2 existing FAQs on the wiki
   Advantage: Single point of info
   Drawback: Breaks existing references.
2/ Keep an official doc under docbook to generate multiple formats (HTML, PDF, RTF, Text, ...)
   Advantage: Easier access whatever context. Put under SVN for each
   version for historicl purposes
   Drawback: Need to write/use a trac2docbook tool. Increase check phase
   before release.
3/ Put the whole doc on the wiki and merge with some existing pages
   Advantage: easy modifications.
   Drawback: Control of the content
4/ Allow for bi-directional modifications (docbook *and* wiki)
   Advantage: easy modifications with vim on my side in docbook
   (copy/paste, search replace, ...)
   Drawback: Need to write/use a docbook2trac tool. Increase check phase

Now some questions:

- Does that sound like a good idea ?
- Who would like to volunteer to help ? (especially neither Victor nor
  myself are native english speakers so fixes are always welcome here).
Note that if there is no volunteer, I'm must less inclined to to more
than the FAQ, as it represents quite some work, and the current status is
for me working well (except for some content but that could be fixed
independently)

The TOC I'd like to propose for the Doc is the following based on the
existing HOWTO:
(Each main chapter could be a dedicated Wiki page)

1. About this Guide
    1.1. Purpose / Scope of this Guide
    1.2. New versions of this document
    1.3. Suggestions / Feedback
    1.4. Aknowledgements
(Updated but not touched that much)

2. QuickStart
(Updated but not touched that much)

3. Overview
(Updated but not touched that much)
    3.1. MondoRescue
    3.2. Mindi
    3.3. Linux Backup
    3.4. Windows Backup
        3.4.1. Windows ME/95/98
        3.4.2. Windows NT4/2K/XP
    3.5. Mondo Rescue and Mindi Linux History
    3.6. System Requirements
        3.6.1. Hardware Requirements
        3.6.2. Kernel Requirements
        3.6.3. Software Requirements

4. Installation
(This should be rewritten, IMO completely using what already exists on
the Web site and the wiki)
    4.1 SVN based installations
    4.2 tar.gz based installations
    4.3 Packages based installations
        4.3.1 Deb based installations
        4.3.2 RPM based installations
        4.3.3 ebuild based installations
        4.3.3 other packages based installations
    4.4 Upstream vs distribution packages
        4.4.1 Deb based installations
        4.4.2 RPM based installations
        4.4.3 ebuild based installations
        4.4.3 other packages based installations

5. Tests
(This one should be increased with a mondoarchive section and also a
debugging part from the Wiki)
    5.1. Testing mindi
    5.2. Testing mondoarchive
    5.3. Testing mondorestore
    5.4. Debugging MondoRescue issues

6. mindi: mini-distribution builder
    6.1. Recommendations
    6.2. Command and Options
    6.3. Distributions specificities

7. Backup
(Updated but not touched that much)
    7.1. Recommendations
    7.2. Backup Commands and Options
        7.2.1. Standard Example With CD-R
        7.2.2. Standard Example With CD-RW
        7.2.3. Standard Example With Tape
        7.2.4. Standard Example With Failsafe kernel
        (This will be removed in 2.2.10)
        7.2.5. Standard Example With Network Backup
    7.3. Distributions specificities

7bis. HOWTO run mondo interactively using cron
(Shouldn't that be rather a section of the previous chapter ?)
(Could someone check whther this is still valid and a problem)
    7.1. Overview
    7.2. Introduction
    7.3. Who should read this?
        7.3.1. Insurance
        7.3.2. Efficiency
    7.4. The Problem
        7.4.1. Cron's environment
        7.4.2. Interactivity
        7.4.3. Screen
    7.5. The Solution
        7.5.1. Briefly
        7.5.2. In Detail

8. Compare
(Updated but not touched that much)

9. Restore
(Updated but not touched that much)
    9.1. Overview
    9.2. Tips and Tricks
        9.2.1. Barebones (Nuke) Restore
        9.2.2. Interactive Restore
        9.2.3. Expert Restore
        9.2.4. Modified partitions - Restore to a different disk geometry
        9.2.5. Advanced
    9.3. Distributions specificities

10. FAQ
(First to be touched and re-formated)
    10.1. Overview and Support
    10.2. General Questions
    10.4. Installation related Questions
        10.4.1. Debian related questions
        10.4.2. Ubuntu related questions
        10.4.3. Fedora related questions
        10.4.4. OpenSuSE related questions
        10.4.5. Mandriva related questions
        ....
    10.5. Environment related Questions
       10.5.1. Hardware
           10.5.1.1 CD/DVD/...
           10.5.1.2 Tapes
           10.5.1.3 USBKeys/disks/...
           10.5.1.4 Raid
       10.5.2. Software
           10.5.2.1 Kernel
           10.5.2.2 Boot Loader
           10.5.2.3 Raid
           10.5.2.4 LVM
           10.5.2.5 FileSystems
           10.5.2.6 Virtualization
    10.6. mindi related Questions
    10.7. mondoarchive related Questions
    10.8. mondorestore related Questions
        10.8.1. Booting issues
        10.8.2. Kernel/Modules issues

What are your feedbacks on this ?
I put copy of this mail at
http://trac.mondorescue.org/wiki/Documentation

Bruno.
--
Open Source & Linux Profession Lead EMEA           / http://opensource.hp.com
HP/Intel/Red Hat Open Source Solutions Initiative  / http://www.hpintelco.net
http://www.HyPer-Linux.org  http://mondorescue.org http://project-builder.org
La musique ancienne?  http://www.musique-ancienne.org http://www.medieval.org

------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Mondo-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mondo-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Mondo-devel] FAQ and Doc.

Tom Metro
Bruno Cornec wrote:
> 2/ Keep an official doc under docbook to generate multiple formats
>    Advantage: Easier access whatever context. Put under SVN for each
>    version for historicl purposes
>    Drawback: Need to write/use a trac2docbook tool. Increase check phase
>    before release.
> 3/ Put the whole doc on the wiki and merge with some existing pages
>    Advantage: easy modifications.
>    Drawback: Control of the content

Using the wiki as the canonical documentation tends to work best for
open source projects. Yes, there is a loss of control, but its usually
easier to review diffs for correctness than to write the documentation
yourself. Anything you can do to reduce the barrier for documentation
contributions in helpful.

Also, providing offline documentation is becoming less and less
relevant. For general documentation I'd be inclined to steer users
towards the online wiki, but include an HTML snapshot of the relevant
wiki pages in the package for completeness.

A fairly simple script could mirror the current state of the wiki to the
SVN repository at the time of release, providing both a historical
record and an offline copy to package with the tool.

Handling the man pages would require a bit more sophistication. Either
they'd be maintained outside the wiki, or you'd need to find a trac2man
converter, which may very well already exist.


> 4/ Allow for bi-directional modifications (docbook *and* wiki)
>    Advantage: easy modifications with vim on my side in docbook
>    (copy/paste, search replace, ...)
>    Drawback: Need to write/use a docbook2trac tool. Increase check phase

I guess that's entirely up to you, if you will be the primary user of
such a tool. Probably not important to the broader mondo community.


> - Does that sound like a good idea ?

Yes.


> - Who would like to volunteer to help ?

It's easy to jump in and help make small incremental improvements (after
going through the hassle of registering at yet another wiki :-) ), and
that's where you'll get the biggest payoff from having the documentation
in the wiki. Bigger projects, like FAQ consolidation, are harder to pull
off when you're just "passing through." And I imagine a tool like mondo,
that gets infrequent use by most of its users, has fewer volunteers than
a tool that's used daily.

Your best bet is to express your vision of how you'd like it to end up
(which you've done) and then do some of the course restructuring to at
least get the raw text loaded into the wiki and the links elsewhere in
the site pointing to the new location. Then volunteers can work on
splitting up sections into pages and refining the text.

  -Tom

------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Mondo-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mondo-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Mondo-devel] FAQ and Doc.

Kevin Cosgrove
In reply to this post by Bruno Cornec-2

Bruno's proposal for a redo of the docs/faq looks fabulous.  I'm not
qualified to write anything.  But, I can read through the English
version and do some editing.

HTH....

--
Kevin



------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Mondo-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mondo-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Mondo-devel] FAQ and Doc.

Hugo Vanwoerkom
In reply to this post by Bruno Cornec-2
Bruno Cornec wrote:
> Hello,
>
<snip>
>
> Now some questions:
>
> - Does that sound like a good idea ?
> - Who would like to volunteer to help ?


Great idea.
I want to help, am more or less a native English speaker, but the range
of mondo's application and my use of it on my system is a problem. Also
the tasks need to be well defined.

Hugo





------------------------------------------------------------------------------
Download Intel&#174; Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Mondo-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mondo-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Mondo-devel] FAQ and Doc.

Danjel Jungersen
In reply to this post by Bruno Cornec-2
On 27 Mar 2010 at 12:17, Bruno Cornec wrote:

> - Does that sound like a good idea ?
Yep...
> - Who would like to volunteer to help ?
Me...
My problem is that I'm not so technical yet..
I consider myself somewhat english speaking, but not natively
english.

Things I can do, could be something like splitting up, fixing links
an so on.
I don't mind writing, but I think it would be wise to have someone
reading it afterwards :-)

Keep up the good work, my only wish is to get bug 280 fixed :-)
Other than that, it runs like a charm, doing daily backups...

Best regards
Danjel
--
Regards

Danjel Jungersen
Jungersen Grafisk ApS
Holsbjergvej 39
DK-2620 Albertslund
Denmark
Phone: +45 43 64 10 00
Fax: +45 43 64 70 00
e-mail: [hidden email]
All MAC-files to: [hidden email]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Need help with something ??
PHP, JavaScript, Linux or semething else
that have my interest ?
http://www.danjel.dk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All mails to and from our system are scanned for virus.
The database is updated daily


------------------------------------------------------------------------------
Download Intel&#174; Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Mondo-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mondo-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [Mondo-devel] FAQ and Doc.

Francesco Talamona
In reply to this post by Bruno Cornec-2
On Saturday 27 March 2010, Bruno Cornec wrote:

> Hello,
>
> Following some exchanges with Victor (co-maintainer) and the mail of
>
> Tom:
> > And this raises another suggestion: multiple FAQs are almost worse
> > than no FAQs. If the Trac ones superseded the ones on the main
> > site, then replace the one on the main site with a link to the
> > Trac pages.
>
> I think it's time for a documentation revamp phase.
> My goals are in order:
>
> 1/ Unify the 2 existing FAQs on the wiki
>    Advantage: Single point of info
>    Drawback: Breaks existing references.
> 2/ Keep an official doc under docbook to generate multiple formats
> (HTML, PDF, RTF, Text, ...) Advantage: Easier access whatever
> context. Put under SVN for each version for historicl purposes
>    Drawback: Need to write/use a trac2docbook tool. Increase check
> phase before release.
> 3/ Put the whole doc on the wiki and merge with some existing pages
>    Advantage: easy modifications.
>    Drawback: Control of the content
> 4/ Allow for bi-directional modifications (docbook *and* wiki)
>    Advantage: easy modifications with vim on my side in docbook
>    (copy/paste, search replace, ...)
>    Drawback: Need to write/use a docbook2trac tool. Increase check
> phase
>
> Now some questions:
>
> - Does that sound like a good idea ?
> - Who would like to volunteer to help ? (especially neither Victor
> nor myself are native english speakers so fixes are always welcome
> here). Note that if there is no volunteer, I'm must less inclined to
> to more than the FAQ, as it represents quite some work, and the
> current status is for me working well (except for some content but
> that could be fixed independently)
>
> The TOC I'd like to propose for the Doc is the following based on the
> existing HOWTO:
> (Each main chapter could be a dedicated Wiki page)

I think is a grat idea, I could help for the Gentoo part, but I'm not a
native speaker too, so my contribution has to undergo further check.

I have no advice about the format and the TOC seems ok to me.

Ciao
  Francesco

--
Linux Version 2.6.33-gentoo-r1, Compiled #1 SMP PREEMPT Sat Apr 10
17:35:50 CEST 2010
Two 2.9GHz AMD Athlon 64 Processors, 4GB RAM, 11659 Bogomips Total
aemaeth

------------------------------------------------------------------------------
Download Intel&#174; Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Mondo-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/mondo-devel
Loading...