Re: [Simulavr-devel] Rework documentation

[Raphaël Martin]

Great idea !
An online accessible documentation is really interesting, especially for 
simulavr newbies (like me)
Your PDF's content and layout looks good to me. HTML version in always 
interesting as well
And well, from my side, a "quick start guide" or "tutorial" would be 
interesting, but is probably not mandatory for now as all the existing features 
are not yet completely documented

Raphaël

Le Wed, Apr 14, 2010 at 10:51:21AM +0200, ThomasK écrivait : 
> Hi @list,
>
> I want to rebuild documentation. First step is done: building web site  
> and documentation with sphinx. Next step: reorder documentation and make  
> plans, what to change and to add. The goal is to substitute texinfo  
> documentation after all. (and to have single source for web site AND  
> documentation)
>
> Web site will have the following content:
>
> - introduction (with a code example and how to use simulavr standalone  
> and with gdb)
> - features (from texinfo documentation)
> - usage (from texinfo documentation)
> - download (new chapter, at the moment it shows old download packages only)
> - build (from texinfo documentation)
> - todo (new, it's at least a copy of TODO file in source root)
>
> Documentation will have the following content:
>
> - copyright (as from texinfo documentation, this is the document  
> copyright, not the program license)
> - introduction (same as web site)
> - features (same as web site)
> - download (same as web site)
> - usage (same as web site)
> - tclgui (from texinfo documentation)
> - build (same as web site)
> - verilog (from texinfo documentation)
> - examples (from texinfo documentation)
> - platform (from texinfo documentation, maybe it's obsolete, in the  
> moment here are some comments for gentoo platform, but old. If this is  
> needed, I'd propose to move it to build chapter, there is also a  
> subchapter for Windows/MinGW)
> - limitations (from texinfo documentation)
> - helpwanted (from texinfo documentation but stripped, so it's very  
> short in the moment)
> - license (new chapter, but in my opinion it's needed, in the moment  
> it's empty)
>
> An example for documentation pdf (MY current state) is to find here:
> http://download.savannah.gnu.org/releases-noredirect/simulavr/manual.pdf
>
> One necessary question: it's necessary to get documentation also in html  
> or it's enough to get it as pdf?
>
> Next question: whats necessary to add? There are 3 positions now on my  
> (!) list:
>
> - checklist and howto add a new controller (from Onno)
> - checklist and howto make a release (from Jörg)
> - howto make web site and upload to savannah
>
> And a connected question: it is useful, to add it straight to one long  
> documentation with all (where are parts, which are useless for users) or  
> it's a better idea to split documentation in 2 parts?
>
> This is my proposal:
>
> - user guide: description, usage, how to get it, usage verilog, python  
> and tcl interface, mailing list, reporting bugs etc., license
> - developers guide: how to build, configure options in detail,  
> checklists and other development howto's, where to get source, mailing  
> list, reporting bugs etc., license
>
> cu, Thomas
>
>
> _______________________________________________
> Simulavr-devel mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/simulavr-devel
>

-- 
Linus Torvalds didn’t design Linux to run on the 386. Intel designed the 386 to 
run Linux.
-- Linus Torvalds facts