YaST/Research/Make Building YaST Documentation Easier (Better)

From openSUSE

Make YaST Documentation Better

Description

We've seen a lot of reports how the current YaST documentation sucks, how it is not well-maintained and how it could be enhanced, but a glamorous documentation is still only a dream. You can be the hero that will make the dream come true! Let the world remember you as the one who has resurrected the YaST documentation from the ashes!

Every time we release a new version of openSUSE / SLES, someone has to svn co a source snapshot, generate some XML documentation from sources, build the HTML documentation, and upload it to http://forgeftp.novell.com/yast/. (Note: ZYpp project does this automatically from the continuous integration process on every scm checkin ).

Some parts of the documentation aren't even necessary to always build as they are rather static (Text Style Guide, Tutorials, ...?).

Customers complain for the lack of migration documentation ie: autoYaST documentation diff between versions.

Relevance to YaST/openSUSE

Everybody needs documentation

Goal

There are several enhancement request or ideas to improve the documentation or the process of building it, but it's often not a priority for developers.

Scope

• Moving static parts of documentation to ... wiki?
• Making the build faster, more reliable, more understandable
• Adding more documentation (examples) to the current code/modules
• Building a PDF form of the documentation
• ...

Related technologies

• WIKI
• XSLT, CSS, HTML
• Make
• ...

Typical use case

@see Relevance to YaST

Required knowledge and skill level

basic to expert skills

Dev. environment/equipment

Does working on the project require a specific environment or equipment - besides a workstation with internet connection?

Participants

If you wish to participate, add yourself here (your user page link, hompe, or e-mail or similar).

• Lukas Ocilka
• Martin Vidner

Division of work and schedule

Waiting for some other ones to join :)

References

• YaST doc SVN with build scripts http://svn.opensuse.org/svn/yast/trunk/doc/
• Source Code Documentation HowTo http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-Documentation.html